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This publication describes how to write telecommunications 
application programs to run under control of the communi- 
cations control program (CCP). The CCP is a feature of 
disk system management that facilitates the implementation 
of telecommunications applications on the Model 10 Disk 
System and Models 12 and 15. 


This manual is intended for programmers who use one or 
more of the following System/3 programming languages: 


@ RPGII 


@ Subset American National Standard (ANS) COBOL 


FORTRAN IV 


@ Basic Assembler 


The introduction to this manual summarizes the purpose 
and operation of the CCP. Subsequent chapters describe 
the standard application program interface to the CCP, 
examples of typical application program logic, application 
programming in COBOL, FORTRAN IV, RPG HI, and 
Basic Assembler, preparing source programs to run under 
the CCP, program testing, and use of the optional 3270 
display format facility of the CCP. 


System/3 Model 8 


The System/3 Model 8 is supported by System/3 Model 10 
Disk System control programming and program products. 
The facilities described in this publication for the Model 10 
are also applicable to the Mode! 8, although Model 8 is 

not referenced. However, the integrated communications 
adapter (ICA) and {focal display adapter are available on the 
Model 8. If you have the CA or local display adapter, it is 
always designated on BSCA line 2. Therefore, you must 
specify line 2 whenever it is required, or enter the BSCA 
OCL statement {// BSCA LINE-2) at execution time. 


It should be noted that not all devices and features which 
are available on the Model 10 are available on the Model 8. 
Therefore, Model 8 users should be familiar with the 
contents of /BM System/3 Model 8 Introduction, 
GC21-5114. 


Preface 


Prerequisites 


The CCP application programmer need not have extensive 
previous knowledge of telecommunications networks, data 
link control, and the characteristics of specific terminal 
devices. This manual assumes, however, that the program- 
mer has a working knowledge of his programming language 
and is familiar with the configuration of the CCP system 

in his installation. 


This manual has no specific prerequisite publications; however, 
many references are made to the following manuals that 

are required by the programmer using the Model 10 Disk 
System and Model 12, and Model 15 respectively: 


@ /BM System/3 Models 10 and 12 Communications 
Control Program System Reference Manual, GC21-7588 


e@ /BM System/3 Model 15 Communications Control 
Program System Reference Manual, GC21-7620 


Also, in order to fully utilize the display format facility 

of the CCP, the programmer must have a basic understand- 
ing of the concepts and operation of the IBM 3270 
Information Display System as given in /BM 3270 Informa- 
tion Display System Component Description, GA27-2749. 


Other publications that are useful to the programmer are 
listed in Appendix C: Bibliography. 
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How To Use This Manual 


In order to gain an overall understanding of the require- 
ments for writing application programs under the CCP, 
read chapters 1, 2, and 3 before reading the chapter that 
applies to your programming language. These chapters 
contain: 


Chapter 1: Summary of the purpose and operation of the 
CCP. 


Chapter 2: Description of the application program inter- 
face to the CCP, independent of any particular program- 


ming Janguage. 


Chapter 3: General description of terminal classes, pro- 
gram types, and CCP application program logic. 


After you have read the first three chapters, read 
thoroughly the chapter that applies to your programming 
language: 

Chapter 4: COBOL 

Chapter 5: FORTRAN IV 

Chapter 6: RPGHU . 


Chapter 7: Basic Assembler 


viii 


If your program will use the 3270 Display Format 

Facility of the CCP to communicate with components of 
the IBM 3270 Information Display System, read chapter 8 
after you have an understanding of CCP application pro- 
gramming in your language. 


Before attempting to write a CCP application program, be 
sure to read Chapter 9: Program Preparation, since that 
chapter contains important disk and unit record file con- 
siderations you must be aware of. 


Reference Aids 


The appendixes provide convenient summaries of applica- 
tion program operation codes and return codes as well as 
a glossary of terms and a bibliography. 


Use the index at the end of the manual to locate specific 
subjects. 


The Communications Control Program (the CCP) is a 
system control program feature of the IBM System/3 Model 
10 Disk System, {BM System/3 Model 12, and IBM 
System/3 Model 15 designed to facilitate the development 
and implementation of telecommunications applications. 
The CCP serves as the control program of a telecommunica- 
tions subsystem, operating in conjunction with disk system 
management (referred to by the abbreviation DSM in this 
manual). 


Under the CCP, an online network of terminals can call 
application programs as needed and access a common set 
of disk files. If sufficient main storage is available, the 
CCP permits several application programs to be executing 
concurrently under its control. 


Communications application programs to be run under 
control of the CCP can be written in any of the high-level 
languages available with Models 10, 12, and 15 — RPG I, 
COBOL, and FORTRAN IV — and in Basic Assembler. 
Individual application programs can be written without 
detailed knowledge of the requirements for programming 
under a telecommunications system and, with few excep- 
tions, as though they are to be run individually, with access 
to all system resources. 


With the facilities provided by the CCP, the System/3 can 
be usec either as a host system or as a subhost system: 
Host System: The System/3 is the central controller of a 
network of start-stop and/or binary synchronous terminals, 
Subhost System: The System/3, while directly controlling 
a group of terminals, is itself a tributary station to a large 
central processor, such as System/370. 


Note: For an introduction to the CCP that includes more 
detailed descriptions of CCP services and relationships be- 
tween the CCP and other System/3 programs, see the CCP 
System Reference Manual, GC21-7588 for Models 10 and 
12, GC21-7620 for Model 15. If you are not acquainted 
with terms and abbreviations used in this manual, you can 
find definitions either in Appendix B. Glossary at the end 
of this manual, or in /BM Data Processing Glossary, 
GC20-1699. 


Chapter 1: Introduction 


CCP STAGES 


Establishing and operating the CCP in a particular environ- 
ment is accomplished in three stages: 


@ Generation 
@ Assignment 


® Operation 


Generation Stage 


CCP generation is the process whereby your installation 
creates its individual version of the CCP. The purpose 

of generation is to establish the required capabilities of the 
CCP by creating a set of CCP object modules and sub- 
routines, unique to the requirements of your installation. 
The process of generation involves: 


1. Describing the type of equipment to be used by the 
communications system and other permanent features 


of the CCP system. 


2. Creating a set of control routines whose specific 
content may be unique to your installation. 


3. Joining the routines by a link-editing process. 
4. Copying appropriate additional supporting routines, 


5. Initializing the control file that the assignment stage 
and the operational stage use (S$CCPFILE). 


CCP Generation is described in CCP System Reference 


Manual, GC21-7588 for Models 10 and 12, GC21-7620 for 
Model 15. 


Introduction 1-1 


Assignment Stage 


CCP assignment stage is a brief process by which one or 
more sets of specific environments in which the CCP can 
run are defined. Each set includes: 


@ Specific items of information pertaining to the entire 
CCP, such as the current password. 


@ Programs that may be run under the CCP and the 
resources that each requires. 


@ Files that are accessible to each program. 
® The current line/terminal configuration. 


@ Symbolic terminal names and the actual terminals to 
which they apply. 


@ Terminal attributes. 


The assignment run need be repeated only when some of 
the specific information given in a previous assignment run 
must be changed. For example, CCP assignment must be 
repeated when new programs and files are to be used under 
the CCP. 


As a programmer, you must be familiar with the contents 
of the CCP assignment sets, since you must be aware of 
characteristics of files, terminals, and communication 
lines available to programs you write. You can determine 
the contents of assignment sets from the listing produced 
by the Assignment List program. 


See CCP System Reference Manual, GC21-7588 for Models 


10 and 12, GC21-7620 for Model 15, for detailed informa- 
tion about CCP Assignment. 
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Operational Stage 


The operational stage begins with Operational startup, when 
the CCP is loaded into main storage. During startup, CCP 
routines open disk files, adapters, and communication lines 
and complete various tables and control blocks. During 
operation, the CCP supervises the environment in which 
your application programs run and provides communi- 
cations services to your programs. The operational stage 

is concluded by shutdown, which is initiated by the system 
operator. During shutdown, the CCP allows programs 

that are currently executing, or that are currently scheduled 
or chained, to finish processing, then it closes communica- 
tion lines, adapters, and files. 


See CCP System Operator’s Guide, GC21-7581 for Models 
10 and 12, or GC21-7619 for Model 15 for a detailed de- 
scription of CCP operation. 


TERMINALS AND FEATURES SUPPORTED 


The following terminals may be used with the communica- 
tions control program. 


Through the multiple line terminal adapter: 


@ 1050 Data Communication System 
Switched 
Multipoint nonswitched 


@ 2740 Communication Terminal Mode! 1 
Basic 
Checking 
Dial 
Dial with checking 
Dial with transmit control 
Dial with transmit control and checking 
Station control 
Station control with checking 


@ 2740 Communication Terminal Model 2 
Station control 
Station control, checking 
Station control, buffered receive 
Station control, buffered receive, checking 


@ 2741 Communication Terminal 
Basic 
Switched 


@ 3767 Communication Terminal (when simulating a 
2740 Model 1) 
Checking 
Dial with checking 
Station control, checking 
(when simulating a 2740 Model 2) 
Station control, checking 


© 3767 Communication Terminal (when simulating a 2741) 
Basic 
Switched 


® Communicating Magnetic Card SELECTRIC® Type- 
writer (appears identical to a 2741 switched) 
Point-to-point switched 


© System/7 (appears identical to a 2740 Model 1) 
Checking 
Dial with checking 
Station contro! with checking 


@ 5100 Portable Computer (when simulating a 2741) 
Basic 
Switched 


@ 5230 Data Collection System (appears identical to a 3741 
Model 2 or 4) 
Point-to-point switched 
Point-to-point nonswitched 


With the binary synchronous communications adapter: 


® 3270 Information Display System 
Multipoint nonswitched 


@ 3275 Information Display Station 
Switched 


@ 3735 Programmable Terminal 
Switched 
Multipoint nonswitched 


@ 3741 Data Station Model 2, Programmable Work 
Station Model 4 
Point-to-point nonswitched or switched 
Multipoint 


®@ System/3 
Point-to-point switched 
Point-to-point nonswitched 
Multipoint with the CCP as contro! station 
Multipoint with the CCP as a tributary 


®@ System/7 Feature 2074 or RPO (see Note) 
Point-to-point switched 
Point-to-point nonswitched 
Multipoint with the CCP as control station 


®@ System/360, System/370 
Point-to-point switched 
Point-to-point nonswitched 
Multipoint with the CCP as tributary 


Terminals that are equivalent to those explicitly supported 
may also function satisfactorily. The customer is respon- 
sible for establishing equivalency. IBM assumes no respon- 
sibility for the impact that any changes to the IBM-supplied 
products or programs may have on such terminals. 


Note: Under BSCA, the System/7 is supported only as 

it is supported by the Multiline/Multipoint BSCA IOCS — 
see /BM System/7 (RPQ) Binary Synchronous Module Pro- 
gramming Guide and Reference Manual, SC34-1510. 
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Chapter 2: Standard Application Program Interface To The CCP 


The standard interface (that is, the procedures and common 
data areas) used by application programs to request the 
CCP to perform communications operations with remote 
terminals or the system operator’s console is composed of 
the following basic elements: 


® Communications Service Subroutine 
® Parameter List 
@ Record Area 


® Aset of communications operations that can be issued 
to the CCP : 


The details of this interface differ stightly among the 
programming languages—RPG II, COBOL, FORTRAN IV, 
and Basic Assembler—but the functions performed by the 
basic elements remain essentially the same. Where the 
interface for a particular language differs from the standard 
interface, you are referred to the chapter covering that 
language. 


In order to perform a communications operation, such as 
writing a message to a terminal, an application program 
must do the following: 


1. Provide storage space within itself for a parameter 
list and record area and specify the format of these 
areas. 


2. Prepare the record area for the operation. 
3. Set the contents of the parameter list. 


4, Invoke the communications service subroutine to 
perform the operation. 


5. Check appropriate return codes to determine the 
result of the operation. 


Since your program may be competing with other programs 
for system resources such as terminals, disk files, and unit 
record devices, the CCP ensures that these resources are 
available to your program before your program is allowed 
to run. Each terminal required by your program is allocated 
exclusively to your program until your program releases it 
(see index entry Release Terminal Operation) or until the 
execution of your program has ended. When either of these 


events has occurred, the terminal is free to be allocated to 
another program (or to enter commands, if it is a command 
terminal), Because the CCP also allocates the use of unit 
record devices, you can code !/O operations using these 
devices as though your program has exclusive control of 
them. (Exception for Model 15 CCP: Your program can 
share use of the 1403 printer with another program running 
concurrently if PRINTER—SHR is specified in the 
PROGRAM assignment statement for your program [see 
CCP System Reference Manual|. You should consider in 
the design of your program that you do not have exclusive 
control of the printer.) 


CCP may receive a request for a program that uses: 
@ Aterminal that is presently allocated to another program. 


® Adisk file that is allocated to another program in such a 
manner that the access methods conflict. For example, 
a currently executing program adds consecutively to a 
file and the program being requested adds to the same 
file. 


® Adisk file is specified as NOSHR on the FILES param- 
eter of the PROGRAM assignment statement or as 
SHARE-NO on the FILE OCL statement. 


The CCP rejects such a program request or queues it, depend- 
ing on the queue status of the terminal (see /O and /NOO 
commands in CCP Terminal Operator’s Guide, GC21-7580). 
When the previous program has terminated, terminals and 
disk files used by that program are available to subsequent 
programs. 


Note: Model 10 and Model 12 CCPs can also queue (/Q) a 
request for a program that uses a unit record device that is 
temporarily unavailable. Model 15, however, normally 
rejects requests for programs that require a unit record 
device that is unavailable. The exception is if the requested 
program uses the printer and the printer is either perma- 
nently allocated to the CCP partition, or spool is intercept- 
ing the CCP partition, and the requested program uses no 
other unit record devices or terminals. 
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COMMUNICATIONS SERVICE SUBROUTINE 


Since RPG Il, COBOL, and FORTRAN IV, do not include 
special statement types for general purpose terminal 1/O 
operations and other communications services (see 
Operations}, the CCP provides one or more communications 
service subroutines to application programs written in each 
language. (For Basic Assembler Programs, a macro instruc- 
tion is provided — see index entry $VC/O macro.) The 
communications service subroutine converts the application 
program’s request into a standard request to the CCP 
communication facilities. 


The communication service subroutine (RPG II programs 
may actually use more than one) must be link edited to 
each application program prior to using the program under 
the CCP. Thus, the communication service subroutine, 
although provided by the CCP, actually becomes a part of 
the application object program. See Chapter 9: Program 
Preparation for procedures for preparing an application 
program to run under the CCP. 


In COBOL and FORTRAN IV, the application program 
initiates a communications operation by issuing a CALL 
statement to the communications service subroutine. 

In RPG II, the program can initiate an operation and 
invoke the communications service subroutine either 
through the SPECIAL or EXIT/RLABL facilities of the 
language. 


PARAMETER LIST 


You must provide a parameter list within your program 
with each request for a communications operation. The 
parameter list specifies the details of the communications 
operation and provides locations within itself where the 
CCP returns information about the results of the operation. 
This chapter describes the parameter list as it is presented 
by the communications service subroutine to the CCP 
communications facilities. In RPG II, the parameter list 

as defined in the user program is somewhat different (see 
Chapter 6: RPG II). 


The parameter list is 16 positions long, consisting of eight 
two-position fields, as shown in Figure 2-1. 


Return Code (Positions 0-1) 
Although this field (see Figure 2-1) must be provided in 


the parameter list, the CCP ignores the contents at the 
beginning of the operation. At the completion of each 
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operation, before returning control to the application 
program, the CCP places a value in this field indicating the 
status of the operation: 

® Operation completed normally (value of zero). 


@ Operation resulted in an (/O error (negative value). 


@ Operation resulted in an exception condition (positive 
value). 


Specific return code values and meanings are given in 
Appendix E: Return Codes. 


Return Code 


Operation Code 


4 Output Length/ Effective Input/ 
Attributes Identifier/ 
Outstanding Invite Inputs 


Maximum Input Length 


16 Positions 
(8 2-position 
fields) 


Address of the Record Area 





Note: In RPG II, the format of the parameter list is 
somewhat different (see Chapter 6: RPG //). 


Figure 2-1. Parameter List 


In order to determine the results of a communications 
operation, you must include coding in your program to 
test the return code. The degree of return code checking 
and the actions taken based on return code checking will 
vary in different applications, however, it is strongly 
recommended that return code checking at the level of 
normal completion (zero return code) or abnormal comple- 
tion (non-zero return code) be done in all programs. 


Examples of testing return codes are given in chapters 4 
through 6. Recommended actions to be taken by your 
program for each return code are given in Appendix E. 
RPG II programmers should see Chapter 6: RPG // for 
additional information concerning handling of return 
codes in that language. 


Operation Code (Positions 2-3) 


For each communications operation (except some RPG II 
operations), this field must contain a code that indicates 
the specific operation to be performed. The contents of 
this field are the same after completion of the operation 
as when the operation began. See Operations, later in 
this chapter, for descriptions of the valid operations and 
operation modifiers that can be issued to the CCP by an 
application program. 


Third Field (Positions 4-5) 


This field in the parameter list can contain four different 
kinds of information: , 


1. Output Length — provided by your program for 
output operations (see Output Operations, following) 


2. Effective Input Length — returned by the CCP (see 
Input Operations, following) 


3. Terminal Attributes Identifier — provided by your 
program (see Acquire Terminal Operation, following) 


4. Count of Outstanding Invite Input Operations — 
returned by the CCP (see /nput Operations and 
Release Terminal Operation, following) 


Output Operations: This field must contain the length of 
the data to be transmitted from your program, that is, the 
number of characters of data you wish to write from the 
record area in your program, not including the six positions 
for the symbolic terminal name and not including line 
control characters, which are added to your data by the CCP. 
(In RPG II, the output length is placed in the output record 
area; see Chapter 6.) 


Input Operations: On each completed input operation, the 
CCP calculates and places into this field the actual length of 
the input data passed to the application program. This 
effective input length does not include the symbolic ter- 
minal name, line contro! characters, backspace characters, 
or data which the CCP cannot pass to the application pro- 
gram when the amount of data received exceeds the size 

of the record area (see Maximum Input Length, the next 
field in the parameter list). However, the effective input 
length does include record separator characters (see index 
entry record separators). The CCP ignores the contents of 
this field at the start of an input operation. 


lf data mode escape is allowed in your CCP system (see 
index entry) and a terminal enters the /RELEASE command 
after entering the data mode escape characters, your pro- 
gram will receive a 08 return code from any of the follow- 
ing input operations: Get, Accept Input, Put-Then-Get, 

and Stop Invite Input (see index entries). The 08 return 
code indicates that the terminal to which the input opera- 
tion was issued is no longer available to your program. In 
this case, CCP places the current number of outstanding 
Invite Inputs for your program (see index entry) in positions 
4-5 of the parameter list. This information is important in 
multiple requesting terminal (MRT) programs (see index 
entry). 


Acquire Terminal Operation: \f you issue an Acquire 
Terminal operation (see index entry) which sets the attri- 
butes of the terminal to be acquired, this field must identi- 
fy the attribute set you want to assign to the terminal. The 
terminal attribute set is defined in the TERMATTR assign- 
ment statement — see CCP System Reference Manual. 


Release Terminal Operation: \f your program releases a 
terminal (see index entry Release Terminal operation) 
and receives a zero return code from the operation, CCP 
places the current number of outstanding Invite Inputs 
for your program (see index entry) in the third field 
(positions 4-5) of the parameter list. 
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Maximum Input Length (Positions 6-7) 


On each operation involving input data, you must enter a 
value into this field representing the maximum number of 
bytes of input data you expect to receive. This value does 
not include the six characters for the terminal name. This 
value must be greater than zero and no larger than the 

size of the record area provided by your program. The CCP 
does not alter this value during the operation. 


Address of the Record Area (Positions 8-9) 


This field is set by the communications service subroutine 
(except in Basic Assembler, where this field is set by the 
$NCIO macro) to contain the main storage address of the 
record area (see Record Area). This field addresses the first 
(leftmost) position of the name field in the record area, not 
the first position of data; therefore, the data actually begins 
at the address given, plus six. For operations not involving 
data transfer, this field may point to a record area contain- 
ing only the name field. 


This field is not present in the parameter list used by 
RPG Ii application programs. 


CCP Work Area (Positions 10-15) 


These positions are used for a work area by the CCP, Your 
program must not use these positions. 


RECORD AREA 


With each communications operation your program issues 
to the CCP (except Shutdown Inquiry), it must provide a 
record area. A record area is an area in the application 
program that consists of two parts. The standard record 
area for operations involving data transfer consists of a 
six-position name field followed by a data area (Figure 2-2). 
Exceptions to this standard format occur for RPG II (see 
Chapter 6: RPG !1) and when the 3270 Display Format 
Facility (see index entry) is used. 


The name field contains either the name of the program (if 
a chained task operation), or the symbolic terminal name 
that is to be involved in the operation. 


The parameter list field containing the record area address 
(Figure 2-1) always points to the leftmost position of the 
name field. Data transfer, however, always occurs into and 
out of the data area segment of the record area. Lengths 
specified in the parameter list for operations involving data 
transfer refer to the length of the data area portion of the 
record area, except in certain RPG II output operations. 
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Data Area 


6 positions 


Number of positions specified by programmer 


Figure 2-2. Standard Record Area 


Program Name 


The program name is the name of the program to be called 
on a Chain Task Request operation (5704-SC2 only). Fora 
task chain operation, your program must place the name of 
the program to be chained in the first six positions of the 
record area (left-justified and padded with blanks if less than 
six characters). If data is to accompany the chain request, 
the data follows the program name in the record area, and 
PGMDATA-YES must be specified on the PROGRAM 
assignment statement (see the Model 75 CCP System 
Reference Manual, GC21-7620) for the requested program. 


Symbolic Terminal Name 


The terminal with which a communications operation is 
performed is identified by a symbolic terminal name in the 
first six positions of the record area (left justified). In most 
operations, the application program must place the name 
into the name field of the record area to specify the termi- 
nal with which to operate; in certain operations, however, 
the CCP places the name into the record area to inform the 
program with which terminal the operation took place. 
Each symbolic terminal name refers to a specific physical 
terminal device. 


Three classes of terminal names are available for use in 
application programs: 


1. User-Defined Names: These are the terminal names 
defined in TERMNAME statements during CCP 
assignment. The structure of these names must 
conform to the following rules: 


@ The first character must be alphabetic (including 
#, $, and @), 


@ Each succeeding character can be either alphabetic 
or numeric. 


® One to five of the six possible positions in the 
name can be blank, but no blanks may be 
embedded between other characters. For example, 
the following names are valid: TERM, 


TdeiH; the following are invalid: TERM(2, 
*TERM2, 


®@ Each terminal name must be unique. 


@ The names CONSOL, ALL, and a name consisting 
of six blanks cannot be user-defined. 


CONSOL: On the System/3 Model 10 and Mode! 12, 
the symbolic name CONSOL refers to the system 
operator's 5471 Printer/Keyboard. On the Model 15, 
the symbolic name CONSOL refers to the system 
operator's keyboard and 3277 Display Station, re- 
ferred to as the CRT/Keyboard. Application pro- 
grams can communicate with thé system operator's 
corisole at any time; however, the console is never 
allocated to the program. Operations issued to the 
console by programs running under the CCP must 

be issued as communications operations; if issued in 
any other way, the results are unpredictable. The 
only operations that can be issued to the console are: 


@® Put 


Put-No-Wait (handled as a Put by the CCP) 


@ Put-Then-Get 


Get Attributes 


Accept Input (to accept only data that accompanies 
the program request) 


The CCP automatically releases the console from any 
program it requests as follows: 


@ If the console requested the program and the 
PROGRAM assignment statement (see CCP 
System Reference Manual!) specifies PGMDATA- 
NO, the console is released when the program 
is loaded. 


@ If the console requested the program and the 
PROGRAM assignment statement specifies 
PGMDATA-YES, the console is released after an 
Accept Input operation results in the console 
program data being passed to the user program. 


Note to Model 10 and 12 users: Programs that use 
symbolic files (see index entry) must allow data to 
be entered with the program request if they could 
be requested by the console (see program request 
command im CCP System Operator’s Guide). These 
programs must also open all physical files to be 
referenced by a symbolic file prior to issuing an 
Accept Input operation. (In RPG II, these files are 


automatically opened prior to the first input 
operation.) 


3. Blanks: Programs that handle only one requesting 
terminal per execution (designated single requesting 
terminal (SRT) programs, see index entry), can issue 
communications operations with six EBCDIC blanks 
(hexadecimal 40) in the symbolic terminal name por- 
tion of the record area.. The CCP interprets the blank 
name as a reference to the terminal that requested the 
program. Upon completion of such an operation, the 
CCP sets the first six positions of the record area to 
contain the name of the requesting terminal. The 
program cannot use blanks after it has released the 
requesting terminal (see index entry Release Terminal 
operation). 


The use of symbolic names for terminals allows programs 
to be relatively independent of the specific terminals. How- 
ever, the programmer must be aware of the type of terminal 
he is using since he must know the record length of the 
device; whether the terminal is capable of input only, out- 
put only, or both input and output; and other information 
(see index entry Get Attributes). The system operator 

can reassign a symbolic name of a terminal (perhaps the 
terminal is out of order or offline) to a different terminal 
during operation of the CCP to allow execution of pro- 
grams using that terminal name. 


Of those operations requiring a six-position symbolic 
terminal name aréa in the record area (only Shutdown 
Inquiry does not) only Accept /nput does not require that 
the area contain a valid symbolic terminal name. The 
contents of the terminal name field for that operation are 
not used by the CCP, 


Whenever you specify a symbolic terminal name other than 
CONSOL in an operation, you must ensure that the termin- 
al is allocated to your program under that defined name. 
The only exceptions to this rule are the Acquire Terminal 
operation, (see index entry) which is a request to obtain 

a terminal, and Get Terminal Attributes, (see index entry) 
which can be requested for any defined terminal name in 
the system. 


Multicomponent Terminal Considerations 


Multicomponent terminals are a special class of terminals 
that can have more than one input and/or output device 
attached. The 1050 Data Communications System is the 
only terminal currently supported by the CCP that is 
considered to be a multicomponent terminal. (Each 
component of the 3270 Information Display System is 
considered a separate terminal and has its own name.) 
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A 1050 system is treated by CCP as if it were one terminal 
regardless of the number of components attached. For 
example, the entire 1050 system is always allocated to a 
program; it is impossible for one component to be allocated 
to one program while another component of the same 1050 
system is allocated to another program. Therefore, any 
program in control of a 1050 system has access to a// 
components of that particular 1050 system. 


As with every other terminal in the CCP system, the 1050 
has a symbolic terminal name. However, this symbolic 
terminal name has a principal input and principal output 
component associated with it. When the symbolic terminal 
name is used in an operation, it refers to the principal 
components. 


You can address other than the principal input and/or 
principal output component of a 1050 system. In addition 
to the symbolic terminal name, you can assign symbolic 
names to a component or pair of components. These are 
called symbolic sub-terminal names. To direct an operation 
to a specific component, use the symbolic sub-terminal 
name associated with that component. 


The following special rules apply to use of multicomponent 
terminals: 


@ Only one Invite Input operation (see index entry) may 
be outstanding to the terminal at one time, regardless of 
the number of input components attached to the 
terminal. 


@ When an operation is issued in which CCP returns a 
symbolic terminal name, such as Accept Input, the 
name returned is always the master terminal name, 
never a symbolic sub-terminal name. 


@ The Acquire Terminal operation must specify a symbolic 
terminal name, not a symbolic sub-terminal name. 


@ The Release Terminal operation must specify a symbolic 
terminal name, not a symbolic sub-terminal name. 


DATA TRANSFER AND TRANSLATION 


The CCP either moves data into your record area or out 
of your record area during a communications operation, 
according to the operation you specify in the Operation 
Code field of your parameter list. In order to know how 
data is transferred to or from a specific terminal, what the 
CCP does with the data, and what your program must do 
with the data, you must know what attributes are assigned 
to the terminal (for example, whether or not a 3270 is 
using the Display Format Facility). 
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Terminal Attributes 


TERMATTR assignment statements (see CCP System 
Reference Manual) define terminal attribute sets for ter- 
minals used under the CCP. Each attribute set is assigned an 
identification number. This number is then referenced 

ina BSCATERM or MLTATERM assignment statement 

to assign a particular set of attributes to a terminal. A 
terminal may have different attributes at different times 
and a single attribute set can be used by more than one 
terminal. See Get Attributes and Acquire Terminal for 
additional information about terminal attributes. 


The terminal attribute sets specify the following informa- 
tion about terminals: 


For BSCA and MLTA terminals: 


. @ Whether or not the CCP will translate data sent to or 


received from the terminal. 


@ lf data is to be translated, whether to force the data to 
uppercase EBCDIC, 


®@ Whether the terminal is auto or manual answer (if on 
a switched line). 


For BSCA terminals only: 

@ Record length 

@ Block length 

@ Input data mode (record, block, or message) 

@ Whether or not the EBCDIC transparency feature is used 
© ITB (intermediate text blocks) used 

®@ Variable length or spanned records used 

@ 3270 Display Format Facility used 

For BSCA terminals on switched lines only: 


@ Whether or not the CCP will! verify exchange identifica- 
tion sequences 


@ Whether the terminal is auto or manual call 


Input Data Transfer 


Data received from a terminal as the result of an input 
operation (see Operations) is moved by CCP from the com- 
munication line buffer to your program's record area. Data 


is received in the seventh and succeeding positions of your 
record area (the program or symbolic terminal name re- 
sides in positions 1-6 of the record area), except in the 
following instances: 


© In RPG II, data may begin in a different position (see 
Chapter 6: RPG II). 


® In 3270 Display Format Facility operations, the format 
of the record area varies with different operations (see 
Chapter 8: 3270 Display Format Facility). 


CCP removes ail teleprocessing tine control characters from 
terminal input data it moves to your record area, except in 
the following cases: 


1. For BSCA terminals, the ITB (intermediate text 
block) character is not removed from input data 
unless fixed length records are being processed in 
ITB record mode, with the correct record length. 
When using variable fength records, the record 
separator character is returned in the record area 
as the last character of data. The effective input 
length returned in the third field of the parameter 
list includes the record separator character. 


2. Programs that communicate with 3270 terminals 
without using the Display Format Facility will 
receive and must send the actual data and display 
control characters necessary for the 3270, such as 
Escape Command, Set Buffer Address, Start Field, 
buffer addresses, and others (see Example 7 in 
chapters 4, 5, and 6 for specific examples in COBOL, 
FORTRAN, and RPG II). 


3. For programs not using PRUF (program request 
under format) that are requested by 3270 terminals, 
the data appended to the program request is not 
processed by the Display Format Facility but is 
passed directly to the user program. See Chapter 3: 
Communications Programming Topics, for further 
description of PRUF. The data is provided in the 
program record area as a continuous string, but 
with no 3270 display control characters. 


The length of the data depends on the value specified in the 
SYSTEM assignment statement (see Assignment Stage in 

the /BM System/3 CCP System Reference Manual for your 
system). The maximum length of the data appended to the 
program request is the value of the PGMREQL parameter 
minus the length of the program name and one blank. 

Since 80 is the maximum value of PGMREQL, the maximum 
length of data that can be appended to the program request 
is 78 characters; any further data in the 3270 buffer at the 


time of the program request is not sent to the program. A 
positive input return code is posted if the data length 
exceeds the length specified. The return code can be tested 
and appropriate action taken. 


For PRUF programs, more than 78 characters of program 
request data can be sent to the user program. The length of 
the data sent to the program can be up to the maximum 
length specified in the PRUFLNG parameter of that pro- 
gram’s PROGRAM statement (see Assignment Stage in the 
/BM System/3 Models 10 and 12 Communications Control 
Program System Reference Manual, GC21-7588, or the 
!BM System/3 Model 15 Communications Control Program 
System Reference Manual, GC21-7620). If the program 
being requested is a PRUF program, CCP will pass the entire 
3270 text stream, control characters and data, to the user 
program at program request time. If PRUF$Z was specified 
on the PROGRAM statement at assignment time, PRUF 
program request data is handled by the display format 
facility. See Chapter 3: Communications Programming 
Topics for a further description of PRUF. 


For chain task requests with data, the maximum amount of 
data that can be transferred is determined by the size of the 
teleprocessing buffer. If other users are active or the tele- 
processing buffer is fragmented, the area for a chain task 
request with data can be further reduced. If the chained 
task is a sort program, the maximum amount of data that 
can be passed by the requesting program is 80 characters. 


Input Data Translation 


The attribute set associated with a terminal specifies 
whether or not data received from that terminal is to 

be translated from the line transmission code (if other than 
EBCDIC) to EBCDIC. If translation is specified, the 
attribute set also indicates whether or not to force to 
upper case all alphabetic characters received. 


Note: All input, including PRUF input, received from a 
terminal in command mode is forced to upper case. 


EBCDIC Transmission Code Used or Translation Requested 


If the transmission code is EBCDIC, or if translation is 
requested, data is presented in EBCDIC in the record area. 
(If translation is requested, the data is converted to 
EBCDIC by the CCP.) No teleprocessing line control 
characters are included in the data except for the BSCA 
ITB character mentioned under /nput Data Transfer. For 
MLTA, backspace characters sent from the terminal are 
not received in the data area; rather, the input data is 
received with all backspacing resolved. Also, if the last 
character of the input is a carriage return, the CCP removes 
it from the input data. 
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All other device control characters (such as 3270 control 
characters, tab key, carriage return in the middle of text) 
are treated as input data characters, Whether or not lower 
case alphabetic characters are translated to their correspond- 
ing upper case characters is determined by the attribute set 
currently associated with the terminal. if upper case trans- 
lation is specified, all alphabetic data input appears in 

upper case EBCDIC in your program’s record area. 


If the length of the data received is greater than the maxi- 
mum input length specified, the excess data is lost 
(truncated) and the effective input length equals the maxi- 
mum input length. If the data length received is less than 
the maximum input length, the effective input length is 
set to equal the data length received, and the remainder 

of your record area is cleared to blanks up to the maxi- 
mum input length. 


Transmission Code Not EBCDIC and Translation Inhibited 


if the transmission code is not EBCDIC and the terminal 
attributes do not specify translation, the CCP places data 
into the record area as it is received, including backspace 
characters, but not including line control characters. The 
application program must be prepared to translate data 
to EBCDIC if the data is to be processed by the program. 
If more data is received than was specified as maximum 
input length in the parameter list, the excess data is lost 
and the CCP sets the effective input length equal to the 


maximum input length. If the data received is less than 
the maximum specified, the CCP sets the effective input 
length to the number of input characters received. The 
record area positions beyond the effective input length are 
set to blanks (X‘40’) (except for MLTA terminals under 
Model 10 and Model 12 CCP, when the content is 
unpredictable). 


Output Data Transfer 


On output operations, the CCP moves data from your record 
area to the communication line buffer and transmits it to 
the terminal you specify. The data must begin in position 

7 of the record area, following the symbolic terminal name, 
(except in some RPG II operations and when 3270 DFF is 
used). No teleprocessing line control characters are needed, 
since CCP adds the necessary line control characters before 
transmitting the data. However, you may include in your 
data any device control characters you desire (see Device 
Contral Characters). 


Note: For BSCA record mode output operations, if the 
output record length is less than the record length specified 
in the terminal attributes set, the number of characters 
specified as the output length (third field of the parameter 
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list) is sent, followed by the number of blanks necessary 
to satisfy the record length specified in the terminal 
attributes set, 


Output Data Translation 

The attribute set associated with a terminal specifies 
whether or not the data to be transmitted to that terminal 
is to be translated from EBCDIC to the line transmission 
code. 


Translation 


If translation is specified in the terminal attributes, the 


-CCP converts data from EBCDIC to the appropriate line 


transmission code. Any device control characters are treated 


as data; thus, if you include device control characters in 
your record area, they must be in EBCDIC form. If invalid 
characters are found during the translation of the data, 
data transfer does not occur and the CCP places a return 
code indicating translation error in the parameter list. If 
more data is sent in one output operation than the line 
buffer for the terminal can hold (in BSCA record mode 
operations, if the output length exceeds the record length 
specified in the terminal attributes set), then the excess 
data is lost (truncated). The return code indicates if there 
was either a translation error or a data truncation. 


Translation Inhibited 


lf translation is not specified, output data is taken from 
your record area and transmitted as is, except for the addi- 
tion of line contro! characters. If more data is to be 

sent in one operation than the size of the line buffer can 
hold (in BSCA record mode operation, if the output length 
exceeds the record length specified in the terminal attributes 
set), then the excess data is lost (truncated). All the data 
that can fit into the line buffer (or record area, for BSCA 
record mode) is sent and a return code indicating the data 
has been truncated is placed in the parameter list. 


Transmitting 3735 FDPs on an ASCII Line 

You must use a special procedure to transmit FDPs (form 
description programs) to a 3735 terminal under the follow- 
ing conditions: 

@ Transmitting on an ASCII line. 

@ CCP to translate input and/or output data. 

This special procedure is necessary because the FDPs, them- 


selves, must not be translated, but all other data, including 
the FDP header and trailer, must be translated. 


The procedure is as follows: 


1, Define two attribute sets for the 3735 terminal at 
assignment time (TERMATTR statements), one 
specifying TRANSLAT—YES and the other specify- 
ing TRANSLAT—NO. 


2. Initially, use the terminal attribute set that specifies 
TRANSLAT—YES for all input from the 3735 (until 
EOT is received). . 


3. Send the FDP header and an EOT using the same 
assignment set (TRANSLAT—YES). 


4. Issue a Release Terminal (Keep-Line) operation 
followed by an Acquire Terminal (Set Terminal 
Attributes) operation, specifying the attribute set 
with TRANSLAT—NO. 


5, Transmit all blocks of FDPs, followed by an EOT. 


6, Issue a Release Terminal (Keep-Line) operation fol- 
lowed by an Acquire Terminal (Set Terminal Attrib 
utes) operation, specifying the attribute set with 
TRANSLAT—YES. 


7. Transmit the FDP trailer in a block by itself. 
8. Transmit all blocks of data, followed by an EOT. 


On switched (dial) lines, sending an EOT to the 3735 
causes the lines to be disconnected. Redialing is necessary 
to continue operations on the line. It is necessary to send 
an EOT before the attributes of the line can be changed. 


If no data is to be read from the 3735, or no data is to be 
sent to the 3735 other than the FDPs, you can code the 
FDP header and/or trailer in ASCII, thereby eliminating 
the need for step 4 or 6 and the EOT in step 3 or 5 of the 
previous procedure, This also eliminates the need to redial 
after sending EOT. 


The data stream to and from the 3735 appears as follows: 
Switched Line Only 
r—- — TRANSLAT-—YES —- — -“—-— Dial 


Input block 1 


Input block n 
| Input EOT | 
| Output FDP Header | 


| | Output FDP block 1] 


| 
| | 
| | 
| LOutput FDP block nf | 
L_ | Output EOT| 2 ord | 


r— — TRANSLAT—YES — 


= 
| 
| 
| 
| 
| 


~<—— Redial 


| Output data block 1 


| 
| 
| 
| 
| | Output data block n| 


Record Separators (Variable Length and Spanned Records) 


Record separator characters for variable length and spanned 
records can be processed by the CCP on record mode input 
‘operations and on any mode of output operations (record, 
block, message). The BSCA terminal (other than the 3270) 
transmitting variable length or spanned records must be 
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defined as supporting record separators at assignment time 
(see TERMATTR statement) and must be defined as record 
mode for input operations. 


The CCP automatically provides record separator 
characters at the end of each record to indicate the end 

of the record, The normal character provided is X‘1E’: 
however, an alternate character may be chosen during CCP 
generation (see SEBSC statement in CCP System Reference 
Manual), The record separator character is considered a 
device control character, not a line control character. 


Note: When sending blocks of field descriptor programs to 
a 3735 terminal for which RECSEP-YES is specified in the 
// TERMATTR assignment statement, you must specify a 
block length less than 476, because a record separator 
character is automatically added to the end of your data 
before it is sent. 


Variable Length Records 


When using variable length records, no record (including 
its record separator character) can be longer than the 
block size defined for the terminal. The record separator 
must be considered a data position when determining 
block sizes and/or line buffer sizes. 


{nput: When using variable length records, you must 
specify a maximum input length in your parameter list 
that is equal to or greater than the longest record you 
expect to receive. The record separator character is 
reflected as part of the effective input length in the 
parameter list. 


For variable length, nonspanned input records, the last 
record separator character may be omitted. In this case, 
the ETB/ETX line control character suffices as a record 
separator, and is received in the user program record area 
in place of the normal record separator. 


Output: The CCP automatically adds record separator 
characters after each record, Do not include the record 
separator in the output length field of your parameter 
list. 
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Spanned Records 


Spanned records can be used under the CCP only if record 
separators are used. A spanned record is not completely 
contained within a single block, but is continued in the 
next contiguous block, as shown in the following example 
of a data format (without ITB and without text trans- 










parency): 
Block R R 
Block R Record 4 e Record 5 
2 S S 


aot BSCA control characters - see Components 
ETB) Reference Manual. 
RS- Record separator, 


Record length, including the record separator, may not 
exceed block length, 


DEVICE CONTROL CHARACTERS 


Device control characters are data characters that control 
certain aspects of terminal operation, such as carriage return 
for typewriter-like terminals and screen formatting for the 
3270 terminal. Device control characters must be included 
in data that is transmitted to or from certain terminals. 
Certain device control characters can be automatically 
inserted into output data by the CCP: 


® Carriage return and idle characters for control of MLTA 
typewriter terminals. 


@ 3270 screen format characters, when the Display Format 
Facility is used (see Chapter 8: 3270 Display Format 
Facility). 


In all other cases, your program must provide the appropri- 
ate device control characters (such as tab characters and 
3270 screen format control characters, when the 3270 Dis- 
play Format Facility is not used). Therefore, before 
writing a program to communicate with any terminal, you 
must understand the device contro! required by the terminal 
and the physical characteristics and capabilities of the 


terminal as described in the component description manual 
for the terminal (see Appendix C: Bibliography). See index 
entries for specific terminal types for additional information 
about the unique requirements of specific terminals. 


MLTA Typewriter Terminals 


As part of the operation code in the parameter list, you can 
indicate whether you want the CCP to insert special device 
control characters into your data for the terminals with 
typewriter characteristics. The terminals considered to 
possess typewriter characteristics include the following: 


®@ 2740, all models or equivalent (including System/7) 


@ 2741, all models or equivalent (including the Communi- 
cating Magnetic Card SELECTRIC® Typewriter) 


@ 1050 with typewriter component (1051/1053). 


Note: \f the 1050 multicomponent terminal number 
specifying all output components is specified, the 1050 
is not treated as a typewriter device. 


Unless you specify otherwise in your operation code, the 
CCP inserts a carriage return and idle characters at the 
beginning of an output record (New Line), if needed to 
assure the output starts on a new line, and at the end of 
an output record (End Line). By means of operation code 
modifiers, you can suppress New Line control characters 
(Not New Line), End Line control characters (Not End 
Line), or both sets of control characters (Not New Line 
and Not End Line). 


You neecl not suppress New Line and End Line for non- 
typewriter terminals. The CCP ignores the indication in 
the operation codes and does not insert the typewriter 
control characters. Also, the CCP inserts New Line and 
End Line characters, unless suppressed; whether or not 
translation is specified. 


New Line 


New Line causes a transmitted message to begin on a new 
line at the typewriter terminal. CCP does this by trans- 
mitting a carriage return and 15 idle characters before your 
data, if the typewriter is not already positioned at the 
-beginning of a new line. The idle characters allow the 
typewriter time to reposition itself as a result of the 
carriage return. It is not always necessary to insert the 
typewriter control characters, since the typewriter may 
already be positioned at the beginning of a new line, CCP 


attempts to keep track of the position of the typewriter 
and considers the typewriter to be positioned at a new 
line under the following conditions: 


@ The last operation was an input operation in which the 
last character received was carriage return, 


@ The last operation was an output operation which 
specified End Line. 


If you specify New Line under either of these conditions , 
CCP does not insert the typewriter control characters. If 
your program is exchanging messages with a typewriter 
terminal, the terminal operator can decrease transmission 
time by keying a carriage return as the last character of his 
input to the program. Thus, when your program responds 
with a Put, CCP will not have to insert the additional con- 
trol characters at the beginning of your output message. 


Note: For a 2740 Model 2 terminal with the buffered 
receive feature, CCP sends the carriage return without idle 
characters, since this terminal allows for completion of 
the carriage return before continuing the printout. 


End Line 


End Line causes the typewriter to be positioned at the 
beginning of a new line after receiving a message. The 
CCP does this by appending a carriage return and 15 idle 
characters to the end of your data. 


‘ 


Message Length Considerations 


You should not allow space for New Line and End Line 
control characters in your record area. When you provide 
an output message in your record area, the CCP must build 
the actual output data stream in the teleprocessing line 
buffer before transmission can occur, Any additional con- 
trol characters added by the CCP must be in the line buffer 
along with your message. (The size of the line buffer is 
specified at assignment time, in the TERMATTR statement 
for BSCA and in the MLTALINE statement for MLTA, see 
CCP System Reference Manual.) Thus, if you want to 
transmit a 40-character message and you specify New Line 
and End Line, a 72-byte data stream is built in the line 
buffer by the CCP. If the data stream is larger than the line 
buffer, your message is truncated while all typewriter 
control characters remain appended to the message. 
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BSCA Terminals 


The CCP performs the following device control for BSCA 
terminals: 


@ The CCP inserts record separators for data transmission 
involving variable length or spanned records, if specified 
in the terminal attribute set associated with the terminals 
(see index entry record separators). 


® If the 3270 Display Format Facility (see index entry) 
is used with 3270 terminals, the CCP provides screen 
format control based on the descriptions of fields 
in the Display Format Specifications. 


In communicating with other communications systems via 
the BSCA, you need not provide device control characters; 
however, the communications interface between the sending 
and receiving programs may require that you provide cer- 
tain control data in your program that is understood by both 
programs, such as data delimiters and record identifiers. 

See Appendix A for additional considerations. 


LINE CONTROL CHARACTERS 


Line control characters are the signals which control 
communication on either an MLTA or BSCA line. Line 
control characters are always removed from or added to 
data by the MLTA and BSCA communications 1OCS 
facilities of the CCP. You need not provide space for line 
control characters in your record area and you need not 
manipulate line control characters in your program. 

MLTA line control is described in the MLTA RPO Program 
Reference and Component Description Manual, GC21-7560; 
BSCA line control is described in the Components Refer- 
ence Manual. 


COMMUNICATING WITH MLTA TERMINALS 


In this discussion, the term ““MLTA terminals” refers to 
any of the terminals fisted in Appendix A as supported by 
the multiple line terminal adapter (MLTA) RPO or their 
equivalents. MLTA terminals perform asynchronous (start/ 
stop) communications with programs through the CCP and 
the MLTA input/ output control system (IOCS), which is 
included in the generated CCP if MLTA terminals are to be 
used. See MLTA RPQ Program Reference and Component 
Description Manual, GC21-7560, for a complete description 
of the MLTA IOCS. 
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Programs communicate with MLTA terminals in a record-by- 
record manner; that is, each 1/O operation in a program 
results in a record being sent or received. The program 

has effective control of the line only while a record is 

being sent or received. After the record has been sent or 
received, another program and/or terminal can use the line. 


COMMUNICATING WITH BSCA TERMINALS 


The term BSCA terminals refers to any of the terminals 
(including host and subhost systems) listed in Chapter 1: 
Introduction as supported by the binary synchronous 
communications adapter (BSCA). BSCA terminals perform 
binary synchronous communications with the Model 10 
Disk System, the Model 12, and the Model 15 through the 
CCP and the multiline/multipoint (MLMP) BSCA IOCS, 
which is included in the generated CCP if BSCA terminals 
are to be used. See /BM System/3 Multiline/Multipoint 
Binary Synchronous Communications Reference Manual, 
GC21-7573, for a complete description of the MLMP 
1OCS. Additional information regarding binary synchronous 
communications can be found ‘in publications listed in 
Appendix C: Bibliography. 


Note: BSCA conversational line control is not supported 
by the CCP. 


Blocking 


When communicating with BSCA terminals, programs send 
or receive blocks of data, A block is the physical unit of 
data that is actually sent or received in each individual 
transmission on a BSCA line. 


A block of data can be composed of one or more data 
records (Figure 2-3). Collecting records into blocks saves 
time when similar operations are performed on each 

record, since it is faster to send and receive more than one 
record at a time than to send and receive records individual: 
ly, 


Se BOCK 


1 block = n records 





—O745300 O3-—- 


In binary synchronous communications, a block of 
data can contain one or more records, 


Figure 2-3. Blocking in Binary Synchronous Communications 


End of Transmission (EOT) 


When communicating with a BSCA terminal, your program 
must perform Get operations until it receives an end-of- 
transmission (EOT) signal from the terminal (Figure 2-4) 
or until a transmission error occurs (resulting in a negative 
return code — See Appendix E). The EOT signal indicates 
the terminal has completed its current transmission. Like- 
wise, your program must send an EOT signal when it has 
finished transmitting to a BSCA terminal (see Put Message 
under BSCA Output Operations), unless a transmission 
error has resulted in a negative return code, 


SBS SBAS Hebaals |f sebatal § Eon) 


<a 











In binary synchronous communications, each block of 
data is transmitted separately. The program retains 
control of the line until EOT indicates that all 
transmission is complete. 






Legend: <= 


L 
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Direction of transmission 






Line control characters 






Figure 2-4. Data Transmission on BSCA Lines 


A BSCA line is dedicated to a program and a terminal 

once communication is initiated and is not freed for use 

by another program or terminal until EOT is transmitted 
(or a negative return code is received from an operation). 
Other terminals on a multipoint line may be allocated to 
other programs; however, a program can only be trans- 
mitting or receiving with one terminal at a time. A program 
that is receiving data from a BSCA terminal cannot transmit 
data to the terminal or communicate with any other term- 
inal on that line until the terminal sends EOT (or a negative 
return code is received), Likewise, when a program is 
transmitting to a terminal on a BSCA line, that line cannot 
be used by any other program or terminal until either 

EOT is sent by the program or a negative return code is 
received by the program. 


BSCA Input Operations 


The CCP provides three levels (modes) of input operations 
for communication with BSCA terminals corresponding 

to three basic units of data: record mode, block mode, and 
message mode (Figure 2-5).. The mode of input used by a 
program with a terminal is specified during the CCP assign- 
ment stage (see TERMATTR statement in CCP System 
Reference Manual). The actual input operations are used 
as described under Operations (see index entry). 
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BSCA record mode input operations result in a single record 











RECORD being moved from the block in the input buffer to the 
MODE program’s record area (each block contains three records in 
Program this illustration). The length of the record area must be at 
Record least as great as the input record length plus the terminal 
Area name (and additional information, in certain RPG II oper- 
ations). 
Message 
nl SS 
' Block : 
t ' 
‘ 6 
\ ; ' 
Record ; ' 


L ‘ LoL : L L L EOT 
Cc i 1 Cr EC ' ' C Cc Cc 
es 


BSCA block mode input operations result in a block of 


BLOCK se records being moved to the program’s record area (without 
MODE | ' : | line contro! characters). Therefore, the length of the record 
i i area must be at least as great as the block length plus the 


Program Record Area terminal name (and additional information, in certain 
RPG 1! operations). 





Message 





EOT 


L : : ee Y ' L 
Cc : : Gc : { Cc 
legen 


MESSAGE BSCA message mode input operations result in an entire 
MODE message (all blocks of input data preceding the EOT signal) 


’ Pe 7 t | being assembled in the input buffer and moved (without 
i i | i i line control characters) to the program’s record area. The 


Program Record Area 


ss 
or 
HL 


record area must be as long as the longest message to be 
received plus the terminal name (and additional infor- 
mation, in certain RPG tl and 3270 DFF operations), 
or the excess portion of the message is truncated. 


Figure 2-5. BSCA Input Operation Modes 
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Blocking has already been described (see Blocking). A 
message consists of a limited number of blocks of data, 
followed by an EOT, that constitute a complete span of 
information that can be received by a program as the 
result of a single input operation. In message mode input 
operations, the CCP attempts to read all input data until 
it receives EOT before moving the data to the program's 
record area, In this way, the BSCA line is freed for use by 
another terminal as quickly as possible. Thus, message 
mode should be used when a limited quantity of data is 
expected (ideally, a single block) on each input operation. 


Message mode is always used with the 3270 Display Format 
Facility. 


Note: \nput modes do not affect output operations. 


BSCA Cutput Operations 


The CCP provides three types of Put operations for use 
with BSCA terminals: Put Record, Put Block, and Put 
Message. Use of these operations in your program is not 
restricted by your program's mode of input operations 
(see BSCA Input Operations). See Operations \ater in 
this chapter, for complete descriptions of all Put opera- 
tions. 


Your program must always send an EOT when it has 
finished transmitting to a BSCA terminal, unless a trans- 
mission error occurs (resulting in a negative return code), 
when the CCP forces an EOT condition and terminates 
the operation. The CCP automatically sends the EOT 
after a Put Message operation and after the Put portion 
of a Put-Then-Get operation. 


Put Record 


The Put Record (or Put-No-Wait Record) operation causes 
a record to be sent to the terminal you specify in your 
program's record area, If block length equals record 
length, each Put Record operation results in a record 
being transmitted on the BSCA line. !f each block con- 
tains several records (specified in the terminal attribute 
set), the block is transmitted when it does not have space 
for another record. Thus, your program may issue several 
Put Record operations before a block of data is actually 
transmitted, (The CCP will automatically issue a Put 
Block operation when a block is complete — see Put 
Block.) \n order to send EOT following Put Record oper- 
ations, your program must issue a Put Message operation 
(see Put Message). 


In fixed-length record processing, CCP either pads a record 
with blanks or truncates a record if the record length does 
not equal the record length specified in the terminal attri- 
bute set (TERMATTR assignment statement). For example, 
if the attribute set defines the record length as 50, and you 
issue a Put Record with an output length of 40, CCP 
actually sends 50 characters; the last 10 characters are 

blank characters. Similarly, if you issue a Put Record 

with an output length of 60, a record of 50 characters 

is sent; the last 10 characters are truncated. 


Put Block 


The Put Block operation causes the current block in the 
output buffer to be transmitted, whether or not the block 
contains all the records it can hold. The next record Put 
by your program starts a new block. A Put Block opera- 
tion may either be: 


@ Accompanied by the final data to be placed in the block 
before it is sent, or 


®@ tssued with a record length of zero, which simply causes 
the block to be sent (if there is no data to be sent, the 
operation is ignored by the CCP). 


When processing fixed-length records (see Put Record), if 
the Put Block operation is used to force transmission of a 
short block, a data length of zero is suggested. If data is to 
accompany the operation, it should be exactly one record 
length, as defined by the terminal attributes set, because 
the normal record truncating or padding is not performed 
by the Put Block operation. 


Put Message 


Put Message causes all data to be transmitted, followed by 
an EOT. A Put Message operation can be: 


@ Accompanied by the final data to be sent before EOT 


@ Issued with a message length of zero, which simply sends 
the EOT signal to the terminal. 


@ Program Request Under Format (PRUF), which 
indicates that the Put Message operation is transmitting 
a program request format out to the 3270 terminal. 


When processing fixed-length records (see Put Record), if 
the Put Message operation is used to indicate the end of 
data, a data length of zero is suggested. If data is to accom- 
pany the operation, it should be exactly one record length, 
as defined by the terminal attributes set, because the normal 
record truncating or padding is not performed by the Put 
Message operation. 
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Put-Then-Get and Put-No-Wait Operations 


These operations have the same basic function as described 
under Operations. Put-Then-Get causes data (record, block, 
or message) to be: transmitted to a specific terminal, follow- 
ed by EOT and a Get operation for the terminal. The 
result of the Get portion of the operation depends on the 
mode of input specified at assignment time (TERMATTR 
statement); the result may be the equivalent of a Get 
Record, Get Block, or Get Message to the terminal. 
Put-No-Wait can be issued at the record, block or message 
level. A Put-No-Wait Record or Put-No-Wait Block are 
identical to Put Record or Put Block. On a Put-No-Wait 
Message, your program neither waits for nor receives a 
return code. 


3284/3286 Printer Consideration 


When issuing operations to a 3284 or 3286 printer (compon- 
ents of the IBM 3270 Information Display System), the 
following situation should be considered: The user program 
issues an operation which starts the printer. Before the 
print operation is complete, the user program issues another 
operation to the printer, resulting in a ‘‘device busy” con- 
dition, for which CCP returns a -14 return code. 


The user program should be written to recognize a -14 
return code from the 3284 or 3286 printer and take some 
appropriate action. Some possible courses of action are: 


@ Retry the print operation a number of times under 
control of a counter in the program. If the operation 
is not accepted after a number of retries, go on to other 
Processing or inform the system operator. See index 
entry Return Codes, Negative (DFF) for special con- 
siderations when using the 3270 Display Format Facility. 
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This kind of action makes heavy use of the communication 
line and adversely affects the performance of other terminals 
using the line. 


@ Perform other operations in the program, such as disk 
1/O or console 1/0, to allow some time for the device 
busy condition to clear. For example, sending a message 
to the system operator requesting a response is a way 
of delaying a retry of the printer operation without 
using system resources needed by other programs. The 
system operator can be asked, for example, to respond 
when the printer is free or after a specified period of 
time. 


@ (Model 15 only) After receiving a device busy return 


code, set the interval timer via the $SIT macro to pause 
your task for a specified amount of time before 
retrying your Put operation. This method requires use 
of an assembler. 


@ (Mode! 15 only) Use the RPG I! operation code TIME 


to obtain the time of day. Repeat the TIME operation 
code until the desired time period has elapsed from the 
initial TIME operation; then reissue the Put operation 
to the printer. This method requires use of the DSM 
transient area and may, therefore, adversely affect 
system performance through heavy use of the transient 
area and disk access mechanism. 


Note: Waiting for the ‘‘device busy” condition to clear by 
looping in your program (not issuing CCP operations) 
prohibits other user programs from executing during the 
loop, and is therefore not recommended. 


OPERATIONS 


This section describes the valid teleprocessing operations 
that can be issued by application pregrams running under 
the CCP. Each description of an opération contains the 
following information: 


Purpose: A brief description of the purpose of the opera- 
tion. 


Operation Code(s): Decimal value, hexadecimal value, and 
RPG II form of each variation of the operation code, A 
summary chart of operation code values is provided in 
Appendix D. 


Additional Requirements: (Information your program must 
provide in addition to the operation code and record area. 


Information Returned: —\nformation the CCP provides to 
your program as a result of the operation, including all 
positive return code values. Descriptions of all return codes 
and a summary chart of return codes by operation type are 
provided in Appendix E. 


Function and Use: A detailed description of the results of 
the operation and rules, considerations, and recommenda- 
tions for using the operation. 


Program Errors 


The CCP checks every operation issued by an application 
program for validity before it performs the operation. | 
Certain conditions are considered to be program logic 
errors, which result in termination of the application 
program. The CCP informs the system operator of the 
termination by printing a message that contains a program 
termination code identifying the error condition, the name 
of the program, and other information. The contents of 
this message and the meanings of the program termination 
codes are given in the /BM System/3 Communications Con- 
trol Program Messages Manual, GC21-5170. 


3270 Display Format Facility Operations 


Requests for 3270 DFF operations are issued in the same 
‘Manner as other requests for terminal operations; that is, 
each request is issued through a communications service 
subroutine and is accompanied by a parameter list and a 
record area, For certain 3270 DFF operations, however, 
you must supply additional information in the record area, 
besides the terminal name. For example, when the display 
format is written to a 3270, the name of the format is 
given in the record area following the terminal name. 


Three operations are unique to 3270 DFF: Copy, Erase, 

and Put Override. These operations are described in 

Chapter 8: 3270 Display Format Facility. Considerations 
for using other CCP operations with 3270 DFF are summa- 
rized in that chapter and are also included in the descriptions 
of CCP operations in this chapter. 
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GET 


The purpose of the Get operation is to read a unit of data 
(record, block, or message) from a specific terminal into 
the record area. 


Operation Codes: 


| RPG II | Meaning 


Normal Get operation 
Get operation with reverse 
interrupt (RVI) (See Func- 
tion and Use of Get for an 
explanation of RVI.) 













0001 1 
0011: 17 








Additional Requirements 


@ Set value of the Maximum tnput Length field in the 
parameter list. 


@ Provide a symbolic terminal name (or blanks) in the 
record area. 


Information Returned 
e Effective Length of Input Data, in parameter list. 
@ Input data, in record area. 


® Count of outstanding Invite Inputs in the third field of 
the parameter list, if the 08 return code is received. 


@ Return Codes: 
0 Successful 
1 Data truncated 
2 EOT 
3 Data truncated and EOT 
5 Data pending (BSCA) 


7 270 CLEAR (No AID is returned in the record 
area) 


8 Terminal no longer available (/RELEASE com- 
mand was successfully entered by the terminal 
operator). 


9 Terminal offline 


-n Negative return codes (1/O errors - see exptana- 
tions in Appendix E). 
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Function and Use of Get 


The Get operation, reads a unit of data (record, block, or 
message) from a specific terminal and places the data in 
the record area. After issuing a Get operation, an appli- 
cation program waits for the CCP to complete the opera- 
tion. The program resumes execution either after the CCP 
has moved the unit of data received from the specified 
terminal to the record area or after the CCP has terminated 
the operation because data transfer cannot succeed. 


If the length of the input data actually received is greater 
than the maximum input length allowed, the data is 
truncated. If the data received is less than that specified, 
the CCP places blanks in the remainder of the record area. 


The attributes of the data, which determine how the input 
data is handled, and the unit of data (record, block or mes- 
sage) are specified by the terminal attribute set currently 
associated with the terminal (see index entry terminal 
attributes). For an MLTA terminal, the unit of data is 
always record. 


For BSCA terminals that acknowledge the receipt of 
reverse interrupts (RVI), the Get operation can be used 

to send an RVI to a terminal while receiving data from that 
terminal. AV/ (see index entry) is generally used as a sig- 
nal from a receiving device to a device that is transmitting 


to interrupt its transmission as soon as possible, usually 
because the receiving device wishes to transmit to the 
sending device. 


Get Operation with 3270 DFF 


When you are using the 3270 DFF, you must issue a Put 
Message or Copy operation to format the display before 
you issue a Get operation to the 3270. See Field Concepts 
and Record Concepts in Chapter 8 for special requirements 
in handling input data. Also see index entry Get operation, 
3270 DFF. 


Specifying the Terminal 


You may, for a Get operation, specify either a defined 
symbolic terminal name or blanks in the record area, A 
defined terminal name must be either the name under 
which the referenced terminal was allocated to the pro- 
gram, or, if this is a multicomponent terminal (see index 
entry), a sub-terminal name subordinate to that name. 
A symbolic terminal name which is not assigned to a 
terminal cannot be used with this operation. 


This operation must not be issued to the CONSOL (5471 
Printer/Keyboard on Models 10 and 12; CRT/Keyboard 
on the Model 15). 


A program can use a blank symbolic terminal name for 
this operation only if the program is a single requesting 
terminal (SRT) program (see index entry). A blank name 
references the terminal that requested the currently execu- 
ting copy of the program. The CCP returns the name of 
the requesting terminal in the record area before returning 
contro! to the program. In the case of an SRT program, 
once the requesting terminal has been released (either by 
using its symbolic name or a blank name), the use of a 
blank terminal name in the record area is no longer valid. 


Considerations 


@ The Get operation must not be issued as the initial 
data-transfer operation to a requesting terminal which 
entered data as part of the program request. The only 
valid operation which may be issued to such a terminal 
at that time is an Accept Input (see Accept /nput oper- 
ation). 


@ The Get operation must not be issued as the initial data- 
transfer operation in a program that was loaded by a 
chain task request. The only operation that can be 
issued in this situation is an Accept Input operation. 


@ This operation can be issued only to a terminal capable 
of transmitting data. 


@ A maximum input length greater than zero must be 
specified in the parameter list for this operation. 


@ The Get operation must not be issued to a terminal 


which has an Invite Input outstanding to it. Should 
it be necessary to read data from such a terminal, 
perform a Stop Invite Input operation. If the Stop 
Invite Input is successful, the Invite Input is can- 
celled and a Get may then be issued to the terminal. 
If the Stop Invite Input fails, then the operation is 
treated as a Get from the specified terminal. 


@ When communicating in record or block mode to a 
BSCA terminal that is on the same multipoint line 
with other BSCA terminals, it is recommended that, 
once input is received from the terminal, Get opera- 
tions should be issued to that terminal until EOT is 
received (or the operation terminates with a negative 
return code). This procedure will free the line for use 
by other terminals as quickly as possible. An alter- 
nate procedure is to issue an Invite Input to the terminal, 
followed by Accept Input operations until the transmis- 
sion is complete (EOT or a negative return code is 
received. 


® In message mode, the EOT return code is never 
returned. 
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PUT 


The purpose of the Put operation is to write a unit of data 
(record, block, message) to a specific terminal. Carriage 
returns are performed for MLTA typewriter terminals 
before and after writing the data (New Line and End Line, 
respectively), unless a modified form of the operation 
code is used to suppress carriage returns. New Line and 
End Line are ignored for BSCA operations. 


The Put operation may specify that the unit of data is to 
be written as the last in the current block (Put Block), 


that is, an EOB (end of block) signal is to be issued follow- 


ing the data and the next unit of data is to begin a new 


Operation Codes 


Meaning: 





RPG II New Line 
2 bbBB yes 
258 BABB yes 
514 KBBB no 
770 BCBB no 
oo «=| | [uues tives 
98 BKFB yes 
290 BABB yes 
0222 546 4BBB no 
0322 802 BCBB no 
oo | 50 [uscn i yes— 
0072 114 44GB yes 
0132 306 BACB yes 
0232 562 ’BCB no 
0332 818 CCB no 
0832 2098 ’HCB yes 
0872 3162 BHGB yes 
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block. The Put operation may also specify that the unit 
of data is the last to be Put in the current transmission 
(Put Message), that is, the EOT (end of transmission) 
signal is to be issued following the data. 


Put Block and Put Message are intended for use with BSCA 
terminals; however, these operations are valid for MLTA 
terminals and have the same effect as a Put operation with- 
out EOB or EOT (Put Record). 


Put Message can be followed by additional input or output 
operations to the same terminal. 











Perform Put operation as follows: 


yes 


no 

Record 
yes 
no 


me ee ee eee 


yes 
yes 
no Block 
yes 
no 


yes 

yes 

no Message 
yes 

no 


Unit of Data 


yes Put overrides message 
used only with DFF. 


yes 


Additional Requirements 


®@ Set value of output length field in the parameter list 
(see exception under RPG II for SPECIAL files). 


@ Provide a symbolic terminal name (or blanks) in the 
record area, 


®@ See index entry Put Overrides for special requirements 
of that operation. 


Information Returned 
@ Return Codes: 


Successful (no exception conditions) 

Data truncated 

Data pending (BSCA) 

Terminal interrupt (MLTA) or RVI (BSCA) 
Terminal offline 

-n Negative return codes {1/O errors and device status 
conditions — see explanations in Appendix E). 


on n= oO 


Function and Use of Put 


The Put operation writes a unit of data to a terminal 
(record, block, or message). On Put operations to MLTA 
terminals, the application program waits for completion 
of the transmission to the terminal. For BSCA devices, 
the program resumes execution upon acceptance of the 
operation by the CCP, except for Put Message. On Put 
Message, control is not returned to the program until 
either the data is transmitted successfully and the EOT 
sent out, or until an error condition occurs. 


Put Operation with 3270 DFF 


With 3270 DFF, you must use a Put Message to write 
the initial display format to the 3270 terminal. To 
override data at the terminal, use the Put Overrides 
operation. See index entry DFF operations for 
additional information and requirements, 


Specifying the Terminal 


You can specify either a defined symbolic terminal name or 
blanks in the record area for a Put operation. A defined 
terminal name must be either the name under which the 
terminal was allocated to the program, or, if this is a 
multicomponent terminal, a sub-terminal name subordinate 
to that name. A symbolic terminal name which is not 
assigned to a terminal can not be used with this operation. 


A Put operation can be issued to the CONSOL. The maxi- 
mum length of output is: 

Models 10 and 12 — 80 

Model 15 — 107 


You can use a blank symbolic terminal name for this oper- 
ation only if your program is an SRT program (see index 
entry). A blank name references the terminal that reques- 
ted the currently executing copy of the program, The 
CCP returns the name of the requesting terminal in the 
record area before returning control to the program. In 
the case of an SRT program, once the requesting terminal 
has been released (either by using its symbolic name or a 
blank name), the use of a blank terminal name in the 
record area is no. longer valid. 


Considerations 


@ The Put operation must not be issued as the initial 
data-transfer operation to a requesting terminal which 
entered data as part of the program request. The only 
valid operation which may be issued to such a terminal 
at that time is an Accept Input (see Accept /nput oper- 
ation). 


@ The Put operation can be issued only to a terminal 
capable of receiving data. 


@ An output length greater than zero must be specified 
for this operation if transmitting to an MLTA terminal. 
However, a zero output length may be specified on Put 
Block operations and Put Message operations to BSCA 
terminals (except on the first such operation) to force 
sending of the current block or message. 


@ This operation must not be issued to a terminal which 
has an Invite Input outstanding to it. 


®@ Put operations to the console, regardless of the form of 
Put operation code used, cause the data (message) to be 
sent to the console. 


@ PRUF Put operations issued to the console are invalid. 


® When using block mode or record mode input with BSCA 
terminals, the following situation can occur and must be 
programmed for: 


1. The program issues an Accept Input; two terminals 
have outstanding Invite Inputs. 


2. The first terminal (T1) provides input data. 


3. The program issues input operations to T1 until EOT 
is received, then issues a Put to T1. 
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4. Prior to the Put to T1, the second terminal (T2) 
provides input data. Since T2 now has control of the 
BSCA line, the Put operation issued to T1 results in 
a 05 return code (data pending on the BSCA line). 


@ When transmitting fixed length data to a BSCA terminal 
using Put Record, any Put Block or Put Message oper- 
ation should not have data specified unless the data is 
exactly one record as specified in the terminal attribute 
set. Truncation or padding of record data is not per- 
formed for Put Block or Put Message operations (see 
index entry Put Record). 


PUT-THEN-GET 


The Put-Then-Get operation transmits a unit of data to a 
specific terminal and then reads data from the same ter- 
minal. Optionally, carriage returns are performed for 
MLTA typewriter terminals before and/or after writing the 
data (New Line and End Line, respectively). Put-Then-Get 
is more efficient than separate Put and Get operations. 


Put-Then-Get is the on/y operation that can be used to 
read data from CONSOL except when an Accept Input is 
used to receive data entered with the program request. 


Operation Codes 


Put (Record) -Then-Get 
operation including New 
Line and End Line on Put. 








Put (Message) -Then-Get 


Put (Record) -Then-Get 
including New Line, but 
suppressing End Line. 






Put (Record) -Then-Get 
including End Line, but 
suppressing New Line. 






Put (Record) -Then-Get 
with neither New Line 
nor End Line. 







New Line and End Line are ignored for 
BSCA terminals and the console. 


Notes: 1. 


2. This operation cannot be used with DFF 
terminals. 
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Additional Requirements 


@ Set value of Output Length field in parameter list (see 
exception under RPG II for SPECIAL files). 


® Set value of Maximum Input Length field in parameter 
list, 


@ Provide a symbolic terminal name (or blanks) in the 
record area. 

Information Returned 

® {nput data in the record area. 

@ Effective Input Length value in parameter list. 


@ Count of outstanding Invite Inputs in the third field of 
the parameter fist, if the 08 return code is received. 


@ Return Codes: 
0 Successful (no exception conditions) 


1 Data Truncated - this return code indicates that 
input data was truncated 


2 EOT - applies to the Get, not returned to the pro- 
gram if Get was message mode (input mode is 
determined by terminal attributes — see index 
entry) 


3 Data Truncated and EOT - applies to the Get 
(MLTA terminals only) 


5 Data Pending - BSCA terminals only 
6 Terminal interrupt (MLTA) or RVI (BSCA) 


7 3270 CLEAR - applies to the Get. No AID is 
returned in the record area. 


8 Terminal no longer available - applies to the Get 
only (/RELEASE command was successfully 
entered by the terminal operator) 


9 Terminal offline - applies to the Put, since Get is 
not performed 


-n Negative return codes (I/O errors and device status 
conditions — see explanations in Appendix E) — 
see Error Return Codes under Function and Use 
of Put-Then-Get for additional information 


Function and Use of Put-Then-Get 


This operation is a combination of a Put operation and a 
Get operation. First, the Put operation is issued to a 
specific terminal. Upon completion of the Put, a Get 
Operation is issued to the same terminal. The application 
program resumes execution upon completion of the Get, 
when the input data resides in the record area. The same 
record area is used for both the Put and the Get (except 
with RPG I! SPECIAL — see index entry Put-Then-Get, 
RPG 11 SPECIAL). 


For BSCA terminals, the operation works as follows: 


@ For Put(Record)-Then-Get, the output data is padded or 
truncated according to normal record processing (see 
index entry Put Record). After the record is sent, EOT 
is sent, followed by the Get operation. 


® For Put(Message)-Then-Get, either the output data is 
the only data sent (if this is message output only), or 
the output data is the last data sent (if the previous 
Operation was a Put Record or Put Block operation). 
No record padding or truncating is performed by the 
Put(Message)-Then-Get operation (see index entry Put 
Message). After the output data is sent, EOT is sent, 
followed by the Get operation. : 


The mode of input (record, block, message) specified by 
the terminal attribute set which is currently associated 
with this terminal (see index entry terminal attributes) 
determines the unit of data received. For an MLTA ter- 
minal, the unit of data is always record. 


Specifying the Terminal 


You can specify either a defined symbolic terminal name or 
blanks in the record area for Put-Then-Get. A defined termi- 
nal name must be either the name under which the terminal 
was allocated to the program or, if this is a multicomponent 
terminal, a sub-terminal name subordinate to that name. A 
symbolic terminal name which is not assigned to a terminal 
cannot be used with this operation. 


The use of a blank symbolic terminal name is valid for this 
operation only if the program is an SRT program (see index 
entry). A blank name references the terminal that requested 
the currently executing copy of the program. The CCP re- 
turns the riame of the requesting terminal in the record area 
before returning control to the program. In the case of an 
SRT program, once the requesting terminal has been re- 
leased (either by using its symbolic name or a blank name), 
use of a blank terminal name is no longer valid. 


Put-Then-Get is the only operation that can be used to get 
data from the system operator’s console (CONSOL), except 
when an Accept Input is used to receive data entered with 
the program request. The maximum input and output 
lengths for this operation are: 

Models 10 and 12 — 80 

Model 15 — 71 


Error Return Codes 


When I/O errors occur on an input operation, the CCP sets 
the effective input length in the parameter list to zero and 
clears the record area to blanks. When errors occur during 
the execution of the Put-Then-Get operation, the operation 
is terminated immediately. Thus, if the error occurs on the 
Put portion of the operation, the CCP does not perform the 
Get, but returns control to your program. In order to deter- 
mine whether an 1/O error (negative return code) occurred 
on the Put or the Get, you can examine the effective input 


length in the parameter list. If the value of this field is the 
same as the output length value specified for the operation, 
then the I/O error occurred on the Put. However, if the 
value has been set to zero, the |/O error occurred on the 
Get. 


Considerations 


@ This operation must not be issued as the initial data- 
transfer operation to a requesting terminal which enterea 
data as part of the program request. The only valid oper- 
ation which may be issued to such a terminal at that 
time is an Accept Input (see Accept /nput Operation). 


®@ This operation can be issued only to a terminal capable 
of both transmitting and receiving data. 


@ A maximum input length greater than zero must be 
specified for this operation. 


@ An output length greater than zero must be specified for 
this operation if transmitting to an MLTA terminal or if 
this is the initial block being transmitted to a BSCA 


terminal. 


@ This operation must not be issued to a terminal which 
has an Invite Input outstanding to it. 


@ This operation must not be used with the 3270 DFF. 
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PUT-NO-WAIT 


The Put-No-Wait operation allows overlap of the output 
operation with continued program execution. Put-No-Wait 
writes a unit of data (record, block, or message) to a 
specific terminal. For MLTA operations and for BSCA 
message operations, your program resumes execution 
immediately upon acceptance of the operation by the 
CCP. Optionally, a carriage return is performed for MLTA 
typewriter terminals before and/or after writing the data 
(New Line and End Line, respectively), New Line and 

End Line are ignored for BSCA operations. 


Operation Codes 









Meaning: Perform Put-No-Wait as follows: 


New Line End Line Unit of Data 





Record 


| Block 


| Message 


Put overrides message 
used only with DFF 
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Additiona! Requirements 


® Set value of Output Length field in the parameter list 
(see exception in RPG II for SPECIAL files). 


@ Provide a symbolic terminal name (or blanks) in the 
record area, 


Information Returned 

@ Return codes (see explanations in Appendix E): 
0 Operation accepted by CCP 
5 Data pending (BSCA) 


9 Terminal offline 


Function and Use of Put-No-Wait 


This operation causes the data in the Put record area to be 
Put to a specific terminal. The requesting program resumes 
execution upon acceptance of the operation by the CCP. 


The Put-No-Wait operation may specify: 


® A record is to be written in the current block (see index 
entry blocking). 


@ An EOB (end of block) signal is to be issued following 
the record and the next record is to begin a new block 
(Put Block). 


@ A record is the last to be Put in the current transmission; 
that is, the EOT (end of transmission) signal is to be 
issued following the data (Put Message). 


Put-No-Wait with EOB, Put-No-Wait with EOT, and PRUF 
Put-No-Wait with EOT are intended for use with BSCA 
terminals; however, these operations are valid for MLTA 
terminals and have the same effect as a Put-No-Wait 
operation without EOB or EOT (Put Record), or without 
PRUF. 


On Put-No-Wait (record) and Put-No-Wait (block) opera- 
tions to a BSCA terminal, the requesting program does not 
resume execution until the specified terminal has gained 
control of the BSCA line. 


Put-No-Wait Operation with 3270 DFF 


If Put-No-Wait is used with 3270 DFF to put a format on 
the display, the CCP changes the operation to a Put 
Message and your program does not regain control until 
the operation is complete. 


Specifying the Terminal 


You can specify either a defined symbolic terminal name or 
blanks in the record area with a Put-No-Wait. A defined 
terminal name must be either the name under which the 
referenced terminal was allocated to the program, or, if 

this is a multicomponent terminal, a sub-terminal name 
subordinate to that name. A symbolic terminal name 
which is not assigned to a terminal cannot be used with 

this operation. Put-No-Wait can be issued to the console, 
but it is treated as a Put (with wait). 


You can use a blank symbolic terminal name for this oper- 
ation only if your program is an SRT program. A blank 
name references the terminal that requested the currently 
executing copy of the program. The CCP returns the name 
of the requesting terminal in the record area before return- 
ing control to the program. [In the case of an SRT program, 
once the requesting terminal has been released (either by 
using symbolic name or a blank name), the use of a blank 
terminal name is no longer valid. 


Considerations 


@ The Put-No-Wait operation must not be issued as the 
initial data-transfer operation to a requesting terminal 
which entered data as part of the program request. The 
only valid operation which may be issued to such a ter- 
minal at that time is an Accept Input (see Accept Input 
operation). 


@ This operation can be issued only to a terminal capable 
of receiving data. 


@ An output length greater than zero must be specified for 
this operation if transmitting to an MLTA terminal or if 
this is the initial block being transmitted to a BSCA ter- 
minal. 


@ This operation must not be issued to a terminal which has 
an Invite Input outstanding to it. 


®@ Since control is returned to the user program before com- 
pletion of the data transfer, no indication as to the success 
or failure or the data transmission is returned to the user 
program. 
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INVITE INPUT 


The purpose of the Invite Input operation is to make a spe- 
cific terminal eligible to send input data. The invited input 
is not made available to your program except as the result of 
a subsequent Accept Input operation (see next operation). 


Operation Code 








Meaning 


Invite Input 


Hex 


0005 





ac 
Additional Requirements 


® Set value of Maximum input Length in parameter list. 


@ Provide a symbolic terminal name (or blanks) in the 
record area. 


Information Returned 
Return Codes: 
0 Successful 


9 Terminal offline 


Function and Use of Invite Input 


This operation causes CCP to make a specific terminal 
eligible to transmit data to the application program. The 
program resumes execution after acceptance of the Invite 
Input operation by CCP. 


More than one Invite Input may be outstanding at one 
time, but not to the same terminal. As each terminal com- 
pletes transmission, the data is queued as input to the user 
program. An Accept Input operation (see next operation), 
causes the first completed input to be made available to 
the application program. 


The attributes of the data and the unit of data (record, 
block, or message) for this operation are those specified in 
the terminal attribute set currently associated with the 
terminal. For an MLTA terminal, the unit of data is 
always record. 
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Invite Input Operation with 3270 DFF 


This operation must not be issued to a terminal under 
3270 DFF until a Put Message or Copy operation has 
placed a format on the display. 


Specifying the Terminal 


You can specify either a defined symbolic terminal name or 
blanks in the record area for the tnvite Input operation. 

A defined terminal name must be either the name under 
which the terminal was allocated to the program, or, if 

this is a multicomponent terminal, a subterminal name 
subordinate to that name. A symbolic terminal name which 
is not assigned to a terminal cannot be used with this 
operation. This operation must not be issued to CONSOL. 


You can use a blank symbolic terminal name for this oper- 
ation only if your program is an SRT program. A blank 
name references the terminal which requested the currently 
executing copy of the program. The CCP returns the name 
of the requesting terminal in the record area before return- 
ing contro! to the program. In the case of an SRT program, 
once the requesting terminal has been released (either by 
using a symbolic terminal name or a blank name), the use 
of a blank terminal name is no longer valid. 


Considerations 


@ An Invite Input operation must not be issued as the 
initial data-transfer operation to a requesting terminal 
which entered data as part of the program request. The 
only valid operation which may be issued to such a 
terminal at that time is an Accept Input (see Accept 
Input operation). 


@ This operation can be issued only to a terminal capable 
of transmitting data. 


@ A maximum input length greater than zero must be 
specified for this operation. 


@ The maximum input length must not be greater than 
the size of the entire teleprocessing buffer (minus 4) 
defined in the current assignment set, or redefined dur- 
ing Startup (four bytes are required for control infor- 
mation used by the main storage allocation routines). 


@ This operation must not be issued to a terminal which 
has an Invite Input outstanding to it. 


ACCEPT INPUT 


The purpose of the Accept Input operation is to gain access 
to the earliest completed record from the terminals to which 
Invite Input operations were previously issued, and to ob- 
tain the data received with a program request or a chain task 
request. Invite Inputs to the other terminals remain in 
effect. 


Operation Code 





Additional Requirements 

© Set value of Maximum Input Length field in the param- 
eter list. 

Information Returned 

® Input data in the record area. 

® Effective length of Input Data, in the parameter list. 


® Symbolic name of terminal from which data was re- 
ceived, in the record area. 


® Count of outstanding Invite Inputs in the third field 
of the parameter list, if the 08 return code is received. 


@ Return Codes: 
0 Successful 
1 Data Truncated 
2 EOT or non-PRUF request to a PRUF program 
3 Data truncated and EOT 
4 Shutdown requested 


7 3270 CLEAR (No AID is returned in the record 
area) 


8 Terminal no longer available (/RELEASE com- 
mand was successfully entered by the terminal 
operator) 


9 Terminal offline 


14 An accept operation for chain task data was 
successful 


15 Chain task data was truncated 


-n Negative return codes (1/O errors — see explana- 
tions in Appendix E) 


Function and Use of Accept Input 


This operation makes data available to your program from 
one of three sources: 


1. A terminal to which an Invite Input operation was 
previously issued by the program (program invite 
operation). 


2: A terminal that presents data along with the program 
request. In this case, the Invite Input is done by CCP 
(system invite operation). 


3. ACCP program that presents data along with a chain 
task request. 


A successful Accept Input operation satisfies the previous 
Invite Input to the terminal from which data was received 
so that there is no longer an Invite Input outstanding to 
that terminal. However, Invite Inputs to other terminals 
remain in effect and can be satisfied by subsequent Accept 
Inputs. 


Your program resumes execution after data from a terminal 
has been made available in the record area. 


On an Accept Input operation, CCP ignores the data in the 
name field of the record area. However, the CCP places the 
name of the terminal from which the data was received in 
this area before returning control to your program. Ona 
chain task request operation, CCP places the name of the 
requesting program in the name field. 


Accept Input Operation with 3270 DFF 


For systems without program request ‘under format or 
when using the 3270 DFF, you must issue a Put Message or 
Copy operation to format the display before you use Invite 
Input and Accept Input operations with the 3270. See 
Field Concepts and Record Concepts in Chapter 8 for 
special requirements in handling input data. See also index 
entry Accept Input Operation, 3270 DFF. 
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DFF non-PRUF programs that use the AID byte position 

to set record identifying indicators on Accept Input oper- 
ations must take into consideration that an Accept Input 
that satisfies a system invite operation does not return the 
AID byte to your record area. The first byte of the pro- 
gram request input data is in the AID byte field (position 

15 if using SUBR92) and could duplicate a valid AID char- 
acter, causing the corresponding record identifying indicator 
to be set on. 


Accept Input Operation for Program Request Data 


When input data is appended to the program request for 
non-PRUF programs, that data is not processed by the 
DFF, but is passed directly to the user program. In this 
case, the Accept Input must not be preceded by a Put 
Message or Copy operation to format the screen. 


The input data is entered into the dynamic TP buffer area in 
acontinuous string. If the data is from a 3270 terminal, the 
first 8 bytes are the control unit and device addresses, the 
_AID byte, and the 3270 control characters. The length 
allocated to the dynamic TP buffer is determined by the 
PGMREQL value (maximum 80 bytes) of the SYSTEM 
assignment statement plus 8 bytes. When the input data is 
passed to the program record area, the 8 bytes and the pro- 
gram name information are also stripped from the input 
data, leaving a maximum of 78 bytes of actual program 
data. Any additional data in the 3270 buffer at the time 

of the program request is not sent to the program. 


When input data is appended to the request for PRUF 
programs (identified by the PRUFLNG keyword given on 
the assignment PROGRAM statement), that data may or 
may not be processed by DFF. The maximum length of 
this data may exceed 78 characters, up to the value speci- 
fied in the PRUFLNG keyword. This data will be processed 
by DFF if the PRUF$Z keyword was included in the assign- 
ment PROGRAM statement. The data stream returned to 
the program for PRUF non-DFF program requests differs 
from that for non-PRUF programs. 
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Program area examples of program request data: 


@ Non-PRUF: 
|aata 
position 1... (up to 78 chatacters) 


(position 15 if RPG I!) 
@ PRUF non-DFF: 


lou | dev aid] c@ sba @@. 


position 1 2 3 45 6 78 
(position 15 if RPG II) 


pgmnamb data sba @@ data... 
9... (up to PRUFLNG parameter) 
@ PRUF DFF: 


[ia pgmnam field2 whe 


position 1 2a (up to PRUFLNG parameter) 
(position 15 if RPG II) 


See Chapter 3 for an explanation of the 3270 control 
characters, aid, sba, etc. 


If the PRUFLNG keyword was given in the PROGRAM 
statement for the requested program, but the last success- 
ful user Put was not a PRUF Put, the CCP will return a 
02 return code to the PRUF program being requested. 
This indicates that non-PRUF data accompanies the 
program request. 


Accept Input Operation for Chain Task Requests with Data 


When data is appended to a chain task request for a DFF 
program, the data is not processed by DFF but is sent 
directly to the input area in the program. This data does 
not contain any 3270 control characters. 


When a program has been loaded via a chain task request 
with data, the program must issue an Accept Input opera- 
tion before attempting any other CCP operation. 


Considerations 


® You should specify a maximum input length in the pa- 
rameter list (and a corresponding record area) large 
enough to accommodate the largest amount of data 
that can be received from an outstanding Invite Input, 
because, if several Invite Inputs are outstanding, you do 
not know which Invite Input will be the first to satisfy 
the Accept Input. 


@ Use caution when issuing Accept !nput or Get operations 
after receiving a Shutdown return code (04). If the 
terminal operators do not key in data to satisfy the 
operations, the program remains in main storage until 
cancelled by the system operator. Stop Invite Input 
operations are recommended to cancel outstanding 
Invite Inputs and still permit processing of any data 
that may be received. 


@ An Accept Input can be issued only under the following 
conditions: 


1. There are one or more Invite Inputs outstanding 
for the program (including any implied Invite 
Inputs due to program requests with accompany- 
ing data). 


2, There are no outstanding Invite Inputs and 


a. The program is defined as a never-ending pro- 
gram, and 

b. The defined maximum number of requesting 
terminals that the program can handle con- 
currently is greater than the current number 
of requesting terminals the program is 
handling. 


® An input length greater than zero must be specified 
for this operation. 


® Accept Input is valid to the console only when issued 
for data with the program request. Any subsequent 
Invite Input to the console results in program termination. 


Shutdown Requested by Operator 


A return code indicating that shutdown has been requested 
by the System Operator may be returned to this operation. 
In this case, the parameter list remains unchanged except 
for the return code field; no input data is received. If you 
still wish to have the operation performed, you must 
reissue the Accept Input. The shutdown-requested return 
code can only occur when there are no completed Invite 
Inputs to satisfy the Accept Input. A shutdown-requested 


return code will be issed to an operation other than Shut- 
down Inquiry only once during the execution of the 
program. 


Every program that uses Accept Input should check for the 
shutdown-requested return code. 


Note: Only the Accept Input need be reissued if you still 
want to have the operation performed, because the Invite 
Input is still in effect. 


STOP INVITE INPUT (OR GET) 


The purpose of this operation is to stop an Invite Input 
previously issued to a specific terminal and, if the Invite 
Input cannot be stopped, to accept (Get) the input. Stop 
Invite Input is used when some event has occurred in the 
program such that the program no longer wants input from 
the terminal. 


Operation Code 


a eR Ee ie ee ee oe ae 


Additional Requirements 










@ Provide a symbolic terminal name (or blanks) in the 
record area. 


@ Set value of the Maximum Input Length field in pa- 
rameter list. 

Information Returned 

® Input data (if Invite Input is not stopped) 


@ Effective Input Length value in parameter list (if 
Invite Input is not stopped) 


@ Count of outstanding Invite Inputs in the third field of 
the parameter list, if the 08 return code is received. 
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@ Return Codes: 
0 Get successful (no exception conditions) 
1 Data truncated 
2 Get successful with EOT 
3 Data truncated with EOT 


7 3270 CLEAR (No AID is returned in the record 
area) 


8 Terminal no longer available (/RELEASE com- 
mand was successfully entered by the terminal 
operator) 


9 Terminal offline 
10 Stop Invite Input successful 


-n Negative return codes (I/O errors and device status 
conditions — see explanations in Appendix E) 


Function and Use of Stop Invite Input 


Stop Invite Input causes the CCP to attempt to cancel an 
Invite Input that has been previously issued to a specific 
terminal. If the Invite Input is stopped successfully, the 
terminal no longer has an Invite Input outstanding. How- 
ever, if the Invite Input cannot be stopped, your program 
must be ready to handle any data received from the ter- 
minal as though your program issued a Get to the terminal. 
Thus, when requesting a Stop Invite Input, your program 
must present all the information needed for a Get opera- 
tion. Your program resumes execution either when the 
Invite Input has been cancelled or when the Get has been 
completed. 


This operation can only be issued to a terminal which has 
an Invite Input outstanding to it. 


If the operation becomes a Get, the attributes of the data 
and the unit of data (record, block, message) for this 
operation are those specified in the terminal attribute 

set currently associated with this terminal (see index entry 
terminal attributes). For an MLTA terminal, the unit of 
data is always record, 
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Specifying the Terminal 


You can specify either a defined symbolic terminal name 
or blanks in the record area for this operation. A defined 
terminal name must be either the name under which the 
terminal was allocated to the program, or, if a multicom- 
ponent terminal, a sub-terminal name subordinate to that 
name. A symbolic terminal name which is not assigned to 
a terminal cannot be used with this operation. This oper- 


ation must not be issued to the system operator console 
(CONSOL). 


You may use a blank symbolic terminal name with this 
operation if your program is an SRT program. The blank 
name references the terminal which requested the currently- 
executing copy of the program, The CCP returns the name 
of the requesting terminal into the record area before 
returning contro! to your program. In the case of an 
SRT program, once the requesting terminal has been 
released (either by using a symbolic terminal name or 

a blank terminal name), the use of a blank name is no 
longer valid. 


Considerations for Using Stop Invite Input 

@ This operation must not be issued as the initial data- 
transfer operation to a requesting terminal which enter- 
ed data as part of the program request. The only valid 
operation which may be issued to such a terminal at 
that time is an Accept Input. 


@ This operation can be issued only to a terminal capable 
of transmitting data. 


@ A maximum input length greater than zero must be 
specified for this operation. 
GET TERMINAL ATTRIBUTES 


The purpose of this operation is to determine the attri- 
butes of a specified terminal. 


Operation Code: 


ae ee 
0008 es, | #6BH Get Terminal Attributes 










Additional Requirements 


@ Provide a symbolic terminal name (or blanks) in the 
record area. 


@ Set value of the maximum input length field in the 
parameter list. 


Information Returned 


® Effective input length value in the parameter list. 


@ Special information in positions 10-15 of the parameter 
list (see Special Information Returned in the Parameter 
List following). 


@ Terminal attributes, in the record area (see Special 
Information Returned in the Parameter List following). 


@ Return codes (see explanations in Appendix E): 


0 Success 


1 Data truncated 


Special Information Returned in the Parameter List 


Get Attributes returns the following information in the 
last three fields of the parameter list. This is the only 
situation in which you may want to reference information 
in these fields. These fields are not returned by the 

RPG II Get Attributes operation. 


Positions 10-11: (Work Area A) 


Contains the address of the Terminal Unit Block (TUB) for 
the terminal specified. The Terminal Unit Block is an internal 
CCP control block used to maintain control information for 
each terminal defined in the system with a MLTATERM 

or BSCATERM statement during the Assignment run. 


Positions 12-13: (Work Area B) 


BSCA Terminal: Contains the block length specified in the 
terminal attributes set associated with this terminal. 


MLTA Terminal: Contains the record length specified in 
the terminal attributes set for the terminal. 


Positions 14-15: (Work Area C) 


BSCA Terminal: Contains the record length specified in 
the terminal attributes set associated with this terminal. 


MLTA Terminal: Contains the record length specified in 
the terminal attributes set for the terminal. 


Information Returned in the Record Area 


As a result of a successful Get Attributes operation, the 
following information is returned in the first 21 positions 
of the data portion of the record area (all information is 
in EBCDIC), 


Position 1 - Allocation Status: Position 1 contains a 
single character that indicates the following information 
about the terminal specified: 


EBCDIC 
Character 


Allocated to this program. All the 
attribute data is provided. 


Allocated to another program. All the 
attribute data is provided. 


Not allocated to a program. All the 
attribute data is provided. 


The specified name was a sub-terminal 

name. The master symbolic terminal 

name has been returned in record area. 

All attribute data applies to the master 

terminal. 

J = Master is allocated to this program. 

K = Master is allocated to another 
program. 

L = Master is not allocated to a program. 


The specified symbolic terminal name is 
not assigned to a terminal. No other 
attribute data is provided. 


Terminal name not defined in the 
system. 
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Position 2 - Terminal Class: Position 2 contains a 
single character representing the class of terminal as 
follows: 







EBCDIC 
Character Terminal Class 


CONSOL 
5471 Printer/Keyboard (Models 10 
and 12),CRT/Keyboard (Model 15) 






MLTA terminal other than 1050 






1050 







3277M1 (480-character), 3284M1, 
or 3286M1 






3277M2 (1920-character), 3284M2, 
or 3286M2 






3275M1 (480-character), with or 
without 3284M3 






3275M2 (1920-character), with or 
without 3284M3 






3735 







Another computer system (CPU) on a 
BSCA line. 






3741 Data Station, 5231 Controller 
Model 2 
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Position 3 - Line Number: Position 3 contains the MLTA 
line or BSCA adapter number to which the terminal is 
attached. Determine whether MLTA or BSCA by check- 
ing position 2. 


EBCDIC 
Character Meaning 


MLTA line 1/BSCA adapter 1 


MLTA line 2/BSCA adapter 2 


MLTA line 3 


MLTA line 4 


MLTA line 5 


MLTA line 6 


MLTA line 7 


MLTA line 8 





Position 4 - Online: Position 4 contains a single charac- 
ter that indicates whether the terminal is logically online 
or offline. This logical status of the terminal can be con- 
trolled by the system operator by use of the /VARY com- 
mand (see CCP System Operator’s Guide). 


The value ‘Y’ indicates the terminal is online; the value 
‘N’ indicates that the terminal is offline. 


Position 5 - Line Type: Position 5 contains a character 
that indicates the type of line on, which the terminal 
resides: 







EBCDIC ] 
Character 


Point-to-Point 










Control Station 






Multi-point Tributary (BSCA only) 


Switched 






Control Station - Switched (MLTA only) 





Positions 6 - 21 - Terminal Attribute Set: These 16 char- 
acters represent the 16 bit settings of the terminal attri- 
bute set currently associated with the terminal. (See 
index entry terminal attributes; also see the TERMATTR 
assignment statement in CCP System Reference Manual.) 


Record 
Area 
Position 


EBCDIC Character-Meaning 


0 - Translate data 
1 - Do not translate data 


0 - Upper case translate 
1 - Lower case translate 


0 - Answer switched line 
1 - Call switched line 


0 - Manual switched line 
1 - Auto switched 


Reserved 
Reserved 
Reserved 


0 - DFF not used for this terminal 
1 - DFF used for this terminal 


0 - Data format not record mode 
1 - Data format is record mode 


0 - Data format not block mode 
1 - Data is block mode 


0 - Data format not message mode 
1 - Data format is message mode 


0- No ITB support 
1 - Support ITB characters 


0 - Non-transparency mode data 
1 - Transparency mode data 


0 - Verify switched line exchange ID 
1 - No exchange ID verification 


0 - No spanned record support 
1 - Support spanned records 


0 - No variable length record support 
1 - Support variable length records 
(record separators) 


Corresponding 
Bit in Attribute 
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Function and Use of Get Attributes 


This operation is used to determine the attributes of any 
terminal defined by a BSCATERM or MLTATERM assign- 
ment statement (see CCP System Reference). It is not 
necessary that a terminal be allocated to a particular pro- 
gram for that program to issue a Get Attributes request 
to that terminal. The attributes of the specific terminal 
requested are available in the parameter list and. the record 
area when the program resumes execution. 


You might use a Get Attributes operation, for example, 
to determine which component of a 3270 is being used 
or whether or not the attribute set defined specifies 
DFF., 


As a result of the Get Attribute operation, 21 characters 
of information are returned in the record area. if the 
maximum input length in the parameter list is less than 
21, then only the number of characters indicated are 
returned. The effective input length field in the parameter 
list indicates the number of characters of information 
returned; the return code indicates data truncation occurs. 


Specifying the Terminal 


Issuing this operation with a terminal name that is not 
defined causes CCP to return a Z in position 1 of the 
record area. 


You may use a blank symbolic terminal name with this 
operation if your program is an SRT program. The blank 
name references the terminal which requested the currently- 
executing copy of the program. The CCP returns the name 
of the requesting terminal into the record area before 
returning control to the program. 


In the case of an SRT program, once the requesting termi- 
nal has been released (either by using a symbolic terminal 
name or blanks), the use of a blank terminal name is no 
longer valid. 


If a sub-terminal symbolic name is given with this opera- 
tion, then the attributes of the master terminal are return- 
ed along with the name of the master terminal to which 
the sub-terminal name is subordinate. 


Considerations 


@ Ifan RPG II program uses position 15 of the input 
record area as the AID byte to set record identifying 
indicators, data from a previous operation can be lost 
or overwritten when a Get Attributes operation is 
performed. 


@ The PF 1, PF 2, and PF 3 keys return the characters 
1, 2, and 3 respectively as the AID character in position 
15 of the record area. A Get Attributes operation can 
also return the characters 1, 2, and 3 as valid allocation 
status information in the same position of the record 
area. 


ACQUIRE TERMINAL 
This operation enables a program to request a specific 


terminal to be allocated to itself and to change the 
attributes of the terminal. 


Operation Code : 


Meaning 


Acquire Terminal — use 
the attribute set currently 
associated with the 
terminal (defined in 
TERMATTR statement) 


Acquire Terminal — 
change the attributes to 
the set identified in third 
field of the parameter list 


Acquire a command- 
mode, non-PRUF 
terminal (5704-SC2 
only) 





Additional Requirements 
@ Provide a symbolic terminal name in the record area. 


@ Provide an attributes identifier in the parameter fist, 
if attributes are to be set by the operation. 


Information Returned 
Return Codes: 
0 Successful 
11. Acquire failed 
Function and Use of Acquire Terminal 


Application programs can issue teleprocessing operations 
only to those terminals that are allocated to them. One 
way to allocate terminals is to specify the terminals in 
the PROGRAM assignment statement (see CCP System 
Reference Manual). However, there may be times when a 
program wishes to have a terminal dynamically allocated 
to it. This can be done with the Acquire Terminal 
operation. 


The Acquire Terminal operation causes the CCP to 
attempt to allocate a specific terminal to a program. If 
the terminal is online, not already allocated to a program, 
and not in command mode (signed on), it is eligible for 
allocation. If operating under control of 5704-SC2, an 
Acquire Terminal operation can acquire a command-mode, 
non-PRUF terminal. A non-PRUF terminal is a 3277 or 
3275 that is not formatted with a PRUF display. 


Along with this operation you may identify a specific 
set of operational attributes to apply to that terminal 
while allocated to your program. If an Acquire Terminal 
operation is to set terminal attributes, then the identifier 
value of the terminal attribute set (as given in the 
TERMATTR assignment statement) must be given in 

the third field of the parameter list (in decimal for RPG II; 
in hexadecimal for other languages). The CCP checks the 


attribute set specified against the terminal type for validity. 


The Acquire Terminal operation is valid if the terminal is 
already allocated to your program only if the Acquire 
Terminal with Set Attributes modifier is issued to change 
the attribute set. (On a BSCA line, the last transmission 
must have completed a message; that is, EOT must have 
been sent or received.) 


Your program resumes execution upon the completion of 
the allocation or upon recognizing that the terminal is not 
available for allocation. 


Specifying the Terminal 


For this operation, you must specify a defined symbolic 
terminal name in the record area. The following names 
may not be specified for the operation: 


@ The name of a terminal already allocated to the pro- 
gram (except the requesting terminal, immediately 
after the first successful Accept Input). 


@ A symbolic sub-terminal name. 


@ A symbolic terminal name that is not assigned to a 
terminal. 


@ CONSOL 


@ Blank terminal name. 


Considerations 


When both DFF and non-DFF programs can be requested 
from the same 3270 terminal, at least two TERMATTR 
statements (DFF3270-YES and DFF3270-NO) must be 
defined in the assignment set for these programs. The first 
terminal attributes set defined in the ATTRID parameter 
of the BSCATERM statement is the default attribute set 
for the terminal. A program that uses the requesting ter- 
minal in a manner other than that defined by the default 
attribute set must perform an Acquire Terminal operation 
with the appropriate attributes identifier to modify the 
terminal attributes. 


CHAIN TASK REQUEST (5704-SC2 Only) 
This operation allows a program to request a second pro- 


gram that is to execute as an unrelated task. Data can 
optionally be passed with the request. 


Operation Code 


Tre [ow | won| tig 


a EE 
002A bbBK Set up a program request 
from this program. 
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Additional Requirements 


®@ Provide the name of the requested program in the name 
field of the record area. 


® Specify either the output length or O (if no data with the 
chain request) in the parameter list (see exception under 
RPG II for SPECIAL files). 


Information Returned 
Return Codes: 


0 Successful operation (Chain Task Request 
accepted) 


12 Request rejected (maximum number of chain 
task requests already queued) 


13 Request rejected (insufficient TP buffer available) 


Function and Use of the Chain Task Request 


When successfully executed by a CCP program, the Chain 
Task Request operation causes a second program to be 
loaded and executed. If the resources (files, terminals, or 
storage) required by the second program are not available, 
the second program is automatically queued. If data is 
presented with the Chain Task Request and PGMDATA- 
YES was specified on the PROGRAM assignment state- 
ment, the data is passed to the second program when that 
program issues its first Accept Input operation. 


Following are some examples of Chain Task Request 
operations. 


Task Chaining from a Program Loaded from the Console: 
PGM11 is loaded from the system operator’s console by 
entering the program request: PGM1BCPGM2. PGM1 
issues an Accept Input operation and receives the data 
CPGM2, and sets up the chain request. 


Console 








t/O Area 


[CPGM26) 


®@ Chain 
Request 


Note: The output length is zero in this example because 
no data is passed between programs. 
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Task Chaining with Data From A Program Loaded From a 
Terminal: PGM1 is loaded from a terminal by entering the 
program request: PGM16CPG2KKDATA. When PGM1 
issues an Accept Input operation, the program receives 
CPG2KKDATA as data, sets up and issues the chain request 
for CPG2, and passes the characters DATA to the requested 
program. When CPG2 is loaded, it issues an Accept Input 
operation to receive the characters DATA. If both accept 
operations are successful, PGM1 receives a OO return code, 
CPG2 receives a +14 return code. 


Terminal 








1/O Area 


|CPG2BBDATA] 


Request 


Note: In this example, the output length is set to four. 


Multiple Task Chaining Involving Sort Programs: PG1 is 
requested from a terminal in this example. No program 
data accompanies this program request. When PG1 re- 
ceives control, it sets up and issues the chain request for 
SORT1. SORT1 is then loaded and begins executing. PG1 
then sets up and issues the chain request for SORTO2. 
When SORTO02 is loaded, it issues an accept operation to 
receive the data passed from PG1, performs the sort func- 
tion, and sets up and issues a chain request for PGM2. 
PGM2 is then loaded and executed. 


Note: It is possible for PG1, SORT1, SORTO2, and PGM2 
to be executing at the same time, provided the programs do 
not have conflicting resource requirements. It is not 
necessary that one program end before another can begin 
executing. 








Terminal 





PG1 





1/O Area 







® Chain 
Request 





|SORT14 
|SORTO2PGM2; 














® Chain SORTO2 


Request 





@ Accept 







® Chain 
Request 






1/O Area 


IPGM2iu/} 


Output length is zero. 
2 Output tength is four. 


Note: CCP/Sort issues a chain request if chaining was spec- 


ified during the generation of the sort program. 


Multiple Chain Requests Involving both Sort and Nonsort 
Programs: PG1 is toaded from the console by entering the 


program request: PG14$S1BS2KP1¥P2. PG issues an 


accept operation to receive the program data, and sets up 
the chain request. Sort programs $1 and S2, and nonsort 


programs operate similarly to the preceding examples. 


Console 
1/O Area 


CONSOLS1BS26P16P2 


|s1 BEBES2BP1bP2 | 





PG1B66S26P1bP2 


S2BBBBP1BP2 


S1BUBbPIBP2 


P1bbbP2 


S2KBBKP2 


P2bbbb 





Note: PG1 and P1 must be set up by the programmer to 
build the chain requests from the input data and to move 
the program name into the name field. S1 and S2, the sort 
programs, are set up to use up to 6 characters of input or 
until the first blank (delimiter) is detected, as the name of 
the program for a chain request. The remaining characters 
are passed as data. 
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Considerations 


@ Symbolic file names that are valid for the requesting 
program are not valid for the requested program because 
the /FILE commands and SYMFILE statements do not 
resolve file name references. 


@ The MAXCHAIN parameter of the SYSTEM assignment 
statement must contain a value greater than zero for 
programs that use the Chain Task Request operation. 
lf a Chain Task Request operation is made and 
MAXCHAIN-O was specified in the assignment set, the 
program is terminated with a 3F termination code. The 
MAXCHAIN parameter has a default value of zero. 


@ Once a Chain Task Request is accepted by CCP and a 
return code returned.to the requesting program, any 
further diagnostics and messages for that request are 
issued to the system operator's console. 


® CCP allocation does not queue requests for unit record 
devices other than the line printer. Ifa Chain Task 
Request operation has been successfully executed, but 
the chained task requires a unit record device (other 
than the line printer) and is not available, the chained 
task is rejected and a message is issued to the system 
operator's console. 


®@ (fa program that issued a Chain Task Request operation 
abnormally terminates, the program requested by the 
task request is allowed to execute. 


@ When a series of task chained programs are active when 
SHUTDOWN is entered, the chained prograrns continue 
executing to normal end of job. 


RELEASE TERMINAL 


The Release Terminal operation enables an application 
program to give up control of a specific terminal in 
order to make the terminal available to the rest of the 
CCP system. 
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Operation Codes 


Release terminal and the 
Communication line. 


Release terminal - keep 
line allocated to the 
program (switched lines 
only). 


Additional Requirements 


@ Provide a symbolic terminal name (or blanks) in the 
record area. 


Information Returned 


© Count of Invite Inputs outstanding for this program, 
in the third field of the parameter list. 


Function and Use of Release Terminal 


When issued to a terminal on a nonswitched communica- 
tion line, a Release Terminal operation causes the CCP to 
release the specified terminal from the program, making 
it available to other programs (if it was not the request- 
ing terminal) or freeing it to enter commands (if it was 
the requesting terminal). When issued to a terminal on 

a switched line, Release Terminal can be issued so that 

it releases the terminal and either: 


1. Keeps the line allocated to the program, or 
2. Releases the line, making it available to other pro- 
grams. 


Keeping the line breaks the connection to the terminal, 
but allows the program to acquire any terminal on the 
line, since no other application program can gain access 
to the line. 


After completion of the Release Terminal operation the. 
third field of the parameter list contains a count of the 
outstanding Invite Input operations for the program, 
including any Invite Input operations issued by the CCP 
because of data accompanying a program request. 


A typical use for the Release Terminal operation is to 
release a requesting terminal from a multiple requesting 
terminal (MRT) program (see index entry) after the pro- 
gram completes its work for the terminal. When an MRT 
program is handling its maximum number of requesting 
terminals, it must release a terminal before it can accept 
a request from a new terminal. 


Your program should issue this operation when it no 
longer neecls a specific terminal, so that the terminal can 
be available to other programs, Possibly the terminal has 
been yielding negative return codes because of a malfunc- 
tion and the program can make no productive use of the 
terminal. The terminal cannot be placed in offline status 
by the system operator while it is allocated to a program. 
Thus, only after an application program releases the termi- 
nal can it be placed offline. 


Specifying the Terminal 


For this operation you may specify either a defined 
symbolic terminal name or blanks in the record area. A 
defined terminal name must be the name under which the 
referenced terminal was allocated to the program. 


The use of a blank symbolic terminal name is valid for 
this operation only if the program is an SRT program. 


The blank name references the terminal which requested 
the currently executing copy of the program. 


None of the following may be specified as the symbolic 
terminal name: 


@ An undefined name (a name not assigned to a terminal) 


@ The defined name of a terminal not allocated to this 
program 


@ A defined name which references a terminal allocated 
to this program, but which is not the name under 
which that terminal was allocated to the program 


@ A sub-terminal name 


@ CONSOL — the console is automatically released by 
the CCP at the beginning of execution of a program 
requested from it. 


Considerations 


@ This operation must not be issued as the initial data- 
' transfer operation to a requesting terminal which 
entered data as part of the program request. The 
only valid operation which may be issued to such a 
terminal at that time is an Accept Input. 


@ This operation must not be issued to a terminal which 
has an Invite Input outstanding to it. 


®@ Inorder to issue Release Terminal on a BSCA line, the 
line must be at EOT. 


@ (Model 10 and Model 12 CCPs) SRT programs using 
symbolic files must open the symbolic file before releas- 
ing the requesting terminal. In RPG Il and FORTRAN, 
all files are opened before any !/O operations can be 
performed by the program; however, COBOL and Basic 
Assembler programs must explicitly open all symbolic 
files prior to issuing a Release Terminal operation to the 
requesting terminal. 


SHUTDOWN INQUIRY 
The Shutdown Inquiry operation is used to determine 


whether the system operator has requested CCP system 
shutdown. 


Operation Code 


ec 


Shutdown Inquiry 





Additional Requirements 


None. 


Information Returned 
Return Codes: 
0 Shutdown not requested 


4 Shutdown requested 


Standard Application Program Interface to the CCP 2-39 


Function and Use of Shutdown Inquiry 


The system operator can request shutdown of the CCP 
at any time. When he does, programs currently running 
should terminate their own execution in a controlled 


manner, rather than be cancelled by the system operator 
without warning. The Shutdown Inquiry operation deter- 


mines whether or not shutdown has been requested and 
sets an appropriate return code in the parameter list. 


If you want your program to perform a controlled termi- 
nation when shutdown is requested, you may include a 
Shutdown Inquiry (or an Accept Input) and a test of 
the return code in your program, For example, perhaps 
you want your program to inform attached terminals 
that the CCP is about to shut down before your program 
terminates. 


WAIT OPERATION (Model! 15 only) 

The Wait operation enables an application program to 
suspend operation for a specified time period (hours/ 
minutes/seconds). 

Note: To use the Wait operation, the timer option must be 


selected at system generation time. 


Operation Code 


Meaning 


Wait Operation 





Additional Requirements 


® Set output length equal to 10. (If using RPG SUBR92, 
set output length to 24.) 


@ Specify the time limit in the user’s record area. 


Information Returned 


Return Code 0 — Successful 
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Function and’ Use of Wait Operation 


This operation enables the application program to issue a 
wait request for the amount of time specified (in decimal) 
in the data area. The data area is specified in the following 
format: 


Terminal name b hhmmss bbb 
1-6 7 8-13 14-16 
where: 
1-6 — Symbolic terminal name 


7 — Blank 

8-13 — hh = number of hours in decimal 
mm = number of minutes in decimal 
ss = number of seconds in decimal 

14-16— Blanks 


Wait Operation Format for RPG SUBR92 


output terminal 
[or code | fength | name | b | nhs | vv 


1-4 5-8 9-14 15 16-21 22-24 
where: 
1-4 —~ bBAD 
5-8 — 0024 
9-14 ~— Symbolic terminal name 
15 — Blank 


16-21— hh = number of hours in decimal 
mm = number of minutes in decimal 
ss = number of seconds in decimal 

22-24— Blanks 


Your program resumes execution after the wait operation 
is completed. 


This chapter describes several aspects of communications 
programming that are important for you to understand 
before you write application programs that use the CCP 
communications interface facilities. (The interface 
facilities are described in Chapter 2 and are further defined 
in later chapters for each programming language.) The 
following topics are discussed: 

® Terminal classes 

@ Program use of terminals 

@ Program types 

®@® Program attributes 


® Communications program logic 


@ Symbolic files 


Switched lines 


TERMINAL CLASSES 


Under the CCP, terminals are divided into two classes, 
based on whether or not they are allowed to enter com- 
mands to the CCP: 


@ Command terminals 

@ Data terminals 

Terminals are designated either command terminals or 
non-command (data) terminals during CCP assignment. 


(See BSCATERM and MLTATERM assignment statements 
in CCP System Reference Manual.) 
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Command Terminals 


A command terminal can request the CCP to perform 
special services; the most significant service request is a 
request to load and initiate a program. Command termi- 
nals must be capable of both input and output, since 
they must be able to transmit commands to the CCP 

and receive messages from the CCP. Once a command 
terminal has requested a program, it is capable of sending 
and receiving data under direction of the program. The 
terminal remains under control of the program until one 


of the following occurs: 


@ The terminal is released by the program. 


@ The program terminates. 


@ The terminal operator enters a /RELEASE command, 
releasing the terminal from the program. 


At that time, the terminal is again allowed to enter com- 
mands to the CCP. A command terminal that is not cur- 
rently signed on to enter commands may also be used by 
a program to send and receive data. 


When a switched line with one or more command termi- 
nals is not under control of a program, the CCP awaits 
calls from command terminals on that line. 


Data Terminals 


A data terminal cannot request CCP services, but can only 
transmit and receive data under control of programs that 
use the terminal. When a program releases the terminal, 
the terminal is not used until it is required by another 
program. 
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A switched line that is connected only to data terminals 
is allocated by the CCP to a single application program 
at a time. Connections are established (answers or calls) 
when the program performs I/O operations referencing 
the symbolic name of a terminal on the line (see index 
entry switched fines). 


A data terminal might have only input capability, only 
output capability, or both input and output capability. 


PROGRAM USE OF TERMINALS 


Your communications program differentiates between 
terminals with which it communicates based on whether 
the terminal requested the program. 


Requesting Terminal 


A requesting terminal is a command terminal that entered 
into communication with your program by entering a 
request for your program while in command mode (see 
CCP System Operator’s Guide for a description of com- 
mand mode and program requesting). Once a requesting 
terminal is in communication with your program, it is in 
data mode and is directed by your program to transmit 
data, receive data, or both. 


From a programming point of view, there are few dif- 
ferences between handling requesting terminals and 
program-selected terminals. However, the following con- 
siderations apply to requesting terminals, but not program- 
selected terminals: 


@ A requesting terminal can include data with a program 
request (if the program is written to handle data with 
the program request, see PROGRAM assignment state- 
ment in CCP System Reference), therefore, the program 
can issue an Accept Input operation as the first opera- 


tion to the terminal (the CCP in effect issues the first 
Invite Input operation to the terminal in this case). 


@ A program that handles only a single requesting termi- 
nal (see Program Types) can use a blank terminal name 
as a reference to the requesting terminal. 


@ The program does not know which terminal will be the 
requesting terminal and, therefore, must determine 
which terminal is requesting by examining the terminal 
name returned with an initial operation. 


Program-Selected Terminal 


A program-selected terminal is a terminal that has not 
requested your program, but is needed by your program 
to transmit data, receive data, or both. 


A program-selected terminal can be attached to your 
program in two ways: it can be either specified at assign- 
ment time as required for your program or acquired by 
your program during its execution by means of an Acquire 
Terminal operation. A program-selected terminal can be 
one of the following: 


@ A data terminal in standby mode. 
@® Acommand terminal in initial mode. 


@ (5704-SC2 only) A command terminal in command 
mode and not formatted by a PRUF display. 


There are hardware characteristics of certain of the MLTA 
terminals that need to be considered in designing and 
writing programs that use program-selected terminals: 


A request for a program that uses a program-selected 
terminal is rejected by the CCP if the terminal is on a 
switched line that is already connected. 


Data Terminals: No special consideration. 


Command Terminals: Command terminals operating 
under 5704-SC1 must be in initial mode in order to be 
program selected. Command terminals operating under 
5704-SC2 must be in either initial mode or in command 
mode and not formatted by a PRUF display in order to 
be program selected. However, while in initial mode, 
command terminals are invited for input by CCP. Thus, 
one of the steps in the allocation of a command terminal 
in initial mode is a Stop Invite Input request from CCP. 
If the Stop Invite Input fails (that is, the read to the 
terminal cannot be cancelled), the program selection of 
the terminal is considered to have failed. Thus, the 
capability of cancelling a read operation is crucial to the 
program selection of command terminals. 


There are certain terminal types for which reads cannot be 
cancelled once they have been issued. Once a read has been 
issued to the terminal, no other operation can be started to 
the terminal until the input operation completes. The 
terminals whose hardware characteristics fall into this 
category are: 


1. 2741 


2. 2741 Dial 


3. 2740 Dial with transmit control 

4, 2740 Dial with transmit control and checking 
5. 3767 simulating a 2741 

6. 5100 simulating a 2741 


Therefore, if these terminals are assigned as command 
terminals, it wil! be extremely difficult for them to be 
program selected. Application programs using these 
terminals should be written so as to handle them as request- 
ing terminals. This may require writing a program as a 
multiple requesting terminal (MRT) program. 


PROGRAM TYPES 


Two general types of communications programs can be 
written to run under the CCP: 


@ Single Requesting Terminal (SRT) Program 


@ Multiple Requesting Terminal (MRT) Program 


Programs are designated as either MRT programs or non- 
MRT (SRT) programs by the PROGRAM statement dur- 

ing CCP assignment (see CCP System Reference Manual). 

If the MRTMAX keyword is used on the PROGRAM state- 
ment, the program is considered an MRT program. (MRT- 
MAX specifies the maximum number of requesters the pro- 
gram can handle concurrently.) SRT and MRT programs 
have different characteristics and place significantly different 
requirements on the application programmer (see Exam- 
ples of Application Program Logic, \ater in this chapter). 


Single Requesting Terminal (SRT) Program 


An SRT program can service the needs of only one 
requesting terminal on each execution (that is, from the 
time the program is initiated by the CCP until it termi- 
nates). A typical example of an SRT program is an 
inquiry program that processes one or more messages 
from its requester and then terminates, using system 
resources only briefly. The program may access or 
update several different files in order to complete its 
processing. An SRT program might also transmit 
batched data to a host system, such as a System/370, 
where the host is the requester of the program. 


An SRT program can be written to acquire (or require, 
by means of the TERMS parameter of the // PROGRAM 
assignment statement) one or more program-selected 
terminals while servicing the requesting terminal. For 


example, perhaps the requester wants information from 
several terminal locations or wants to send information 
to other locations. An example of such a program might 
be an inquiry program that serves a credit office applica- 
tion. The requesting terminal asks for information about 
a customer from terminals in other offices by issuing a 
message to program-selected terminals in those offices 
specifying the customer identification. The attached 
offices reply with the latest credit information. 


If sufficient resources are available, the CCP can load and 
initiate separate, duplicate copies of an SRT program, each 
copy servicing a different requesting terminal. If resources 
are not available, second and subsequent requests for the 
program may be placed on a queue by the CCP (see /O 
command in CCP Terminal Operator’s Guide). Multiple 
copies of an SRT never-ending program are not permitted 
under the CCP. 


Multiple Requesting Terminal (MRT) Program 


An MRT program can service requests from one or more 
terminals each time it is executed. An MRT program 
may be written to handle multiple requesting terminals 
concurrently. The maximum number is specified by the 
MRTMAX keyword of the PROGRAM statement at 
assignment time. Requests for the program that are 
received while the program is already handling its maxi- 
mum number of terminals are queued by the CCP (if the 
requester has indicated queuing) to be honored when the 
program has released a terminal; therefore, you need not 
check this in your program. Only a single copy of any one 
MRT program can be in main storage at a time. 


New requesting terminals are attached to an MRT pro- 
gram by means of Accept /nput operations (see index 
entry). A program is notified that a new terminal is 
attached by receiving a new termina! name from an 
Accept Input. ; 


MRT programs must maintain status information regarding 
several requesting terminals in order to remember which 


~ terminals are attached and the status of each terminal rela- 


tive to the program. 


You must explicitly release a requesting terminal once 
your program has completed the processing required by 
the terminal (see index entry Release Terminal operation). 
If not released, the terminal remains allocated to the pro- 
gram until the program terminates. An MRT program 
should be written to terminate when it has no more 
requests to service, unless the program is defined as a 
never-ending program (see Program Attributes). 


Communications Programming Topics 3-3 


Many application programs, both order entry and inquiry, 
could be written in either single requester or multiple 
requester form. If a program is likely to be often requested 
from more than one terminal concurrently, it is more 
efficient to code the program as an MRT program, since 
the MRT version is not as likely to cause resource conflicts 
as are-numerous requests of an SRT program. Also, an 
MRT program should take less main storage space than 
separate copies of an SRT program. 


An MRT program can be defined as MRTMAX-1 on the 
PROGRAM assignment statement. In this case, only one 
request is processed at a time, as in an SRT program, but 
subsequent requests for the program can be queued to the 
same copy of the program if the requesting terminal has 
elected to queue requests (/O command). An MRT program 
defined in this way does not have to keep track of multiple 
attached terminals; however, the program cannot process 
multiple requests concurrently and only one copy of the 
program can be in main storage at a time. 


If an MRT program is specified as NEVEREND-NO and 
MRTMAX-1 (capable of handling only a single requesting 


terminal), the program is reloaded each time it is requested, 
even if it is in storage at the time of the request. 


SPECIAL PROGRAM ATTRIBUTES 


The two general communications program types—SRT and 
MRT —may have additional special attributes: 


@ Never-ending 


Serially reusable (Models 10 and 12) 


Dedicated (Models 10 and 12) 


©@ Program request under format 
® Sort 


The PROGRAM assignment statement specifies whether a 
program has any of these attributes. 
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Never-Ending Program 


If a program is to be requested frequently throughout the 
CCP run and if sufficient main storage is available, it can 
be defined as a never-ending program (NEP). An NEP, once 
it has been loaded and initiated by the CCP, does not 
terminate (except in an unusual situation) until the CCP is 
shut down. Under Model 10 and Model 12 CCP, once an 
NEP jis loaded, the main storage it occupies is permanently 
unavailable for other programs, even if it terminates in an 
unusual situation. Under Model 15 CCP, the main storage 
occupied by an NEP is released for use by other programs 
if the NEP terminates in an unusual situation. 


An NEP with no work to do (no outstanding Invite Inputs) 
issues an Accept Input operation and waits until it is 
requested again. See Disk File Considerations in Chapter 9: 
Program Preparation for a Model 15 CCP consideration in 
this situation. 


When using NEPs, you should be aware of facts concerning 
system resource allocation: 


® While a particular system resource is allocated to a NEP, 
requests for programs that also require the resource will 
be rejected, regardless of the queuing status (/O or 
/NOQ) of the requesting terminal. 


@ When an NEP requires a system resource that is already 
allocated to another program, the request for the NEP 
will be rejected without regard to the queuing status of 
the requesting terminal. Under Model 15 CCP, a request 
for a NEP can be queued if CCP is handling the maximum 
number of tasks or if user program area is not immedi- 
ately available. 


An NEP should either check for the shutdown return code 
or issue the Shutdown Inquiry operation so that CCP shut 
down can be successfully completed. 


When writing an SRT program as a never-ending program, 
be aware that second and subsequent requests for the pro- 
gram are rejected by the CCP. 


To ensure that the required main storage is available for 
the never-ending program, it is recommended that all 
never-ending programs (only one of which can be an SRT 
program) be loaded into main storage prior to requesting 
any other programs. Main storage fragmentation could 
result if never-ending programs are not started as the initial 
programs in the system. 


Note to Model 10 and 12 Users: \t is especially important 
to load NEPs first if they use the 3270 Display Format 
Facility, because the Display Format Facility is loaded into 
the user program area for execution. 


Note to Model 15 Users: CCP always loads NEPs at the 
opposite boundary of the user program area from non- 
NEPs to avoid fragmentation of this area, which could 
otherwise severely impair CCP performance. 


Serially Reusable Program (Models 10 and 12) 


A serially reusable program terminates normally after 
executing and can be re-executed without requiring a 

fresh copy of the program to be loaded in main storage. 

A serially reusable program must restore data areas and 
modified instructions to their initial condition prior to 
reusing those data areas and instructions when the program 
is reinitiated. Only COBOL and Basic Assembler programs 
can be written to be serially reusable. Never-ending 
programs cannot be specified as serially reusable. 


Use of serially reusable programs can increase CCP effi- 
ciency, especially if the programs are requested frequently, 
since the need for repeated loading of the program can be 
avoided in some cases. If other programs are being request- 
ed and loaded, however, timing of the requests may be such 
that, when a subsequent request for the serially reusable 
program is entered, the main storage space previously 
occupied by the serially reusable program is already 
occupied by another program. In this case, the serially 
reusable program must be reloaded. 


Dedicated Program (Models 10 and 12) 


When a program defined as a dedicated program is running, 


it must be the only program running in the CCP program 
fevel, even though multiprogramming is allowed by the CCP. 
It may not be initiated while other prograrns are running 
and other programs may not be initiated while it is running. 
This program attribute applies only in CCP systems that 
allow more than one program to be executing concurrently. 


You might want to designate a program as dedicated if it 
requires exclusive use of disk files that are otherwise 
shareable, for example, a program that performs summary 
operations at a particular cut-off time, such as day-end or 
month-end, when concurrent operations on the files are 
not desired. A dedicated program might also be used in 
applications where fast response time is important and 
the program relies on exclusive access to all communica- 
tion lines, disk files, and other system resources. 


Program Request Under Format 


With a non-PRUF request, the maximum amount of data 
that can be passed to a user program, as a program request, 
is 78 characters. This is not an efficient use of the 3270 
terminal buffer. An efficient method of using the 3270 
terminal is to write a short SRT program which will put a 
display at a terminal, and then go to end of job. The ter- 
minal operator can then fill in the display with data, cause 
attention (PF key or ENTER key) and have the display at 
the terminal essentially request another program. The 
whole display will be used as program request data. This 
concept of requesting programs and passing up to a full 
screen of data to the requested program is called Program 
Request Under Format (PRUF). 


The use of PRUF will provide the following capabilities: 


@ More than one field of data may be passed as program 
request data. 


@ More than 78 characters of data may be accepted as 
program request data. 


@ The AID character is passed as program request data 
to PRUF programs, but not to non-PRUF programs. 


@ The data passed to the user program with the program 
request may or may not be processed by DFF under 
format control if the program being requested is a 
PRUF program. However, DFF does not process non- 
PRUF program request data. 


@ Main storage can be used efficiently, as a program need 


not be in main storage during a lengthy terminal 
operator keying operation. 
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A program is defined as a PRUF program if the PRUFLNG 
parameter is specified in the assignment PROGRAM state- 
ment. The PRUFLNG parameter specifies the maximum 
length of program request data to be sent by the terminal. 
If the PRUF program is also a DFF program, the PRUF$Z 
parameter is specified in the PROGRAM statement. This 
gives the name of the format which will be used by DFF to 
format the program request data. (See the /BM System/3 
Models 10 and 12 Communications Control Program 
System Reference Manual, GC21-7588, or the /BM 
System/3 Model 15 Communications Control Program 
System Reference Manual, GC21-7620, for a complete 
description of these keywords.) 


To inform CCP that the next program request from a 3270 
terminal will be a PRUF program request, user program A 
(which may be a PRUF or a non-PRUF program) executes 
a PRUF-Put operation to the 3270 terminal as its last 
output operation prior to releasing that terminal or going 
to end-of-job. If the terminal receiving the PRUF-Put 
operation was a requestor of the program issuing the 
PRUF-Put, that program must have ENDMSG-NO specified 
on its PROGRAM statement. 


Before returning the terminal to command mode status, 
CCP will reserve an area from the TP buffer, equal in length 
to the maximum PRUFLNG, as a temporary hold area for 
the program request data from that terminal. !t should be 
noted that CCP will only reserve a TP buffer area equal in 
length to the PGMREQL, as specified in the SYSTEM 
statement, if the last user output operation to that terminal 
is not a PRUF-Put operation. 


The first field received from the 3270 must be the program 
name of the PRUF program to be requested and must begin 
in row 1, column 2 or later on the screen. The program 
name must be either entered in the first field on the screen 
(that field defined as an input field) or sent to the screen 
(by a PRUF-Put operation) in the first field defined as an 
output/input field. The terminal operator then keys in 
data to all needed input fields on the screen. 
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When all the needed fields have been keyed in, press the 
ENTER key, a PF key, or insert a card into the card 
reader (this action is device dependent). Now the program 
request for program B enters the system. If program B is 
a non-DFF program, the following data will be passed as 
program request data to program B: 


culdev_ |faid 
1 2 3 


c@ |sba |@@ |pgmnamé pgmdata... 
45 6 7-8 49... 


Note: \f the program is written in RPG II, these fields start 
in column 15 of the input specifications, 


where: 
cu = Control unit address of the 3270 terminal 
dev = Device address of the 3270 terminal 
aid = AID character 
c@ = Cursor address 
sba = Set buffer address (X11) 
@@ = Address of start of pgmnam field 
pgmnam = Name of program B 
b = EBCDIC character for a blank (X’40') 
pgmdata = Remainder of 3270 text stream or the 


number of characters specified by 
PRUFLNG parameter, whichever is 
smaller. 


A PRUF program request will return & plus PGMNAM length 
plus 7 additional character of data more than a program 
request for anon-PRUF program. If a program B is a DFF 
PRUF program, DFF will attach the PRUF$Z format to the 
program using that format for contro! and move data into 
program B’s input record area at program request time. (See 
Chapter 8 for a description DFF handling of accept input 
data.) 


The following considerations apply when running CCP 
assignment sets with PRUF programs: 


@ PRUF-Put operations to the system console are invalid. 


@ If the 3270 terminal has been formatted by a PRUF- 
Put operation, and the program being requested is a 
non-PRUF program, CCP will reject the program request. 


@ if PRUF is not active on the 3270 terminal, and the 
program being requested is a PRUF program, CCP will 
issue a 02 return code following the Accept Input 
operation. The program request data returned in this 
case will begin with the first character of data follow- 
ing the program name and a blank. This will not have 
been processed by DFF. 


@ If PRUF is active on the terminal, all system messages 
to that terminal will be output in positions 82 through 
160. Therefore, these positions should be used with 
caution at program request time to PRUF programs. 


@ A terminal which had a PRUF-Put format sent to it has 
this condition (PRUF-type terminal) terminated by 
the next non-PRUF Put operation sent to the terminal, 
or if the terminal CLEAR key is pressed. 


Sort Programs (5704-SC2 Only) 


Sort programs must be generated offline from CCP but can 
be executed as user programs under CCP. Multiple sort 
programs can be active under CCP at one time providing 
each program has a unique name, and unique work and 
output files. A minimum of three files must be defined on 
the FILES parameter of the PROGRAM assignment state- 
ment for a sort program: 


®@ An input file with CG access. Input files can be opened 
with CO, 10, and IOU access methods but the opening 
program must terminate successfully before the file can 
be shared. Up to eight input files can be defined. 


@ Awork file with CA access and specified as nonshareable. 


® An output file with CO access and specified as nonshare- 
able. After a sort program has completed successfully, 
the output file can be opened using CA, CG, CO, CU, 
DG, or DU access methods. 


Note: The sort input file cannot be specified as the sort 
output file. The use of SYMFILE statements and /FILE 
commands to resolve sort file name assignments is sup- 

ported, but do not attempt to overlay the input file with 
the output file using the SYMFILE and /FILE facilities. 


After a sort program has terminated successfully, the input, 
work, and output files are available to other sort and non- 
sort programs. 


When a sort program is requested from a terminal, addition- 
al modules with the prefix $DG are loaded by the sort pro- 
gram. These additional modules (initially supplied on the 
system pack) must be on the same pack from which the 
sort program was loaded. For example, if a sort program 
has been placed on the program pack (PACK-PROGRAM 
specified on the PROGRAM assignment statement), the 
$DG modules must be copied to the program pack from 
the system pack. This can be accomplished using the 
following OCL: 


// COPY FROM-nn, TO-nn, LIBRARY-O, RETAIN-P, 
NAME-$DG.ALL 


Because of space considerations, it may be more convenient 
to put the sort program on the system pack. 
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Once a sort program has started, the requesting terminal is 
released and is free to perform other operations. All sort 
messages indicating the status of the sort program are issued 
to the system operator’s console after the requesting ter- 
minal is released. 


Note: \f another program is allowed to update the sort in- 
put file at the same time that a sort program is processing 
the file, improper results can occur. For this reason, either 
specify NOSHR for the sort input file in the assignment 
set, or allow input only programs to access the file while 
the sort program is executing. See CCP System Reference 
manual for your system and the /BM System/3 Disk Sort 
Reference Manual, SC21-7522, for additional information 
about sorts. 


If shutdown is requested, an active sort program is allowed 
to complete execution to normal termination. 


Sorts and Task Chaining 


When a sort program is to issue a chain request, the name of 
the requested program and the data (if required) must be 
passed to the sort program with the program request. The 
sort program interprets the first six characters (or up to the 
first blank if the name is less than six characters) as the 
name of the program to be requested. The remaining data 
is passed as data along with the chain request. 


If more than 80 characters of data are passed to a sort pro- 
gram, the sort program issues a CCP DATA TRUNCATED 
message to the console, and issues the chain request, even 
though the data has been truncated. 


If CCP is handling the maximum number of chain requests 
when a sort program issues a chain request, CCP issues a 
TASK CHAIN UNSUCCESSFUL message to the console. 

In this case, the sort program is allowed to complete exe- 
cution, but the chain request is neither issued nor executed. 


For an example of a sort program issuing a chain request, 
see index entry: chain task request. 
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EXAMPLES OF APPLICATION PROGRAM LOGIC 


Programs that do not communicate with online terminals 
are most often designed to run in batch processing mode; 
that is, one program completely finishes its processing 
before the next program begins to run. Often, the pro- 
gram processes a large number of data records which con- 
tain similar data in similar format. Such a program prob- 
ably uses only a few data files; perhaps it builds a tempor- 
ary file and updates a permanent file. (Communication 
terminals can also be used to advantage in batch process- 
ing mode.) 


Most communications programs, on the other hand are 
designed for a very different environment, characterized 
by online processing; that is, data enters the computer 
directly from the point of origin and is transmitted 
directly to where it is used. The communications environ- 
ment often includes several terminals, each making 
requests in a random manner, each request requiring the 
execution of a different program. Each program might 
process only a single transaction at a time for the 
terminal, affecting several different files. The majority 
of communications programs utilize this type of process- 
ing, which requires program logic different from that 
required for batch processing. 


The following examples illustrate the typical logic 
required to deal with: 


@ A single requesting terminal 


e@ A single requesting terminal and program-selected 
terminals 


® Multiple requesting terminals 


@ Multiple requesting terminals and program-selected 
terminals 


Single Requesting Terminal 


Figure 3-1 shows the program logic that might be used in 
a program that deals with only a singie requesting termi- 

nal on each execution. The numbered notes further ex- 

plain aspects of the logic. 


Oo If data is expected with the program request, no 
Invite Input is required, since the first Accept Input 
will return the requester’s name and data in the 
record area. {f data is expected with the program 
request, an Accept Input must be issued. 


@ A Put operation with a blank terminal name causes 
the name of the requesting terminal to be returned 
in the record area. Invite Input can then be issued 
to that terminal. If no data is expected with the 
program request, a Get operation with a blank termi- 
nal name can be used after the Put operation instead 
of the Invite Input and Accept Input operations. 


® If data is expected with the program request, the 
first input operation is an Accept Input. Subsequent 
input operations can either be Accept Input or Get 
operations. !f Accept Input is used, Invite Input 
must be issued prior to the Accept Input except for 
the first Accept Input operation when data is ex- 
pected with the program request. 
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Figure 3-2. Program that Communicates with a Single Requesting Terminal and Program-Selected Terminals 








Single Requesting Terminal and Program-Selected Terminals 


Figure 3-2 illustrates the logic that could be used by a 
communications program to deal with a single requesting 
terminal and one or more program-selected terminals. The 
numbered notes further explain characteristic aspects of 
this type of logic. 


Oo These steps (enclosed by the broken fine) are per- 
formed only the first time through the program. A 
program can determine which terminals to select in 
various ways: 


® The terminals required by the program are 
specified at assignment time and the terminals 
have been allocated to the program before it 
gains control. 


@ The program knows which terminals it needs, 
but must acquire them itself. 


@ The program does not know which terminals to 
select. The program might have to obtain this 
information from the system operator, a termi- 
nal, or from the data he is processing. 


When the program knows which terminals to select, 
it can acquire them (if not already allocated by 
assignment), Put a ‘‘Hello’”’ message, and Invite 
Input, as required. 


@ 


When a program is capable of handling more than 
one terminal, it may need to set aside a separate 
work area for each. The program would use the 
work area to retain enough information to remem- 
ber what it has previously received from each termi- 
nal. When, for example, input data consists of more 
than one part, a separate routine often processes 

each different part. A complete input message might 
consist of a customer name or number, an order num- 
ber, item numbers, quantities, prices, and other infor- 
mation, entered as separate lines of input data and, in 
fact, as separate transmissions from the terminal. The 
program must be able to determine which portion of 
the data it is processing, where to store that data in 
the work area, and which routine processes that por- 
tion of the data, 


When a program-selected terminal has completed a 
message sequence, the program must determine 
whether it wants additional input from the terminal. 
For example, if the program has received an end-of- 
input signal or if the system operator has issued the 
SHUTDOWN command (and the program recognizes 
the shutdown return code), the program should not 
issue an Invite Input to the terminal. 


If any other program-selected terminals have input 
messages to transmit (have outstanding Invite Input 
operations issued to them). the program finishes 
processing them. When all input from the program- 
selected terminals and the requesting terminal has 
been processed, the program terminates. 
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Figure 3-3. Program that Communicates with Multiple Requesting Terminals and No Program-Selected Terminals 
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Multiple Requesting Terminals 


Figure 3-3 shows the program logic that might be used in 
a program that deals with multiple requesting terminals. 
The numbered notes further describe key steps in the 
logic. 


© The Invite Input is bypassed the first time through 
since it is not Known which terminal requested the 
program until after the Accept Input operation. 


@ When the program. has received the final portion of 
a message sequence from a particular terminal, it 
must determine whether it wants additional input 
frorn the terminal.. If, for example, the terminal 
has indicated that this is the last message it will 
send or if the system operator has issued the 
SHUTDOWN. command to shutdown the CCP 
(and the program recognizes the shutdown return 
code), the prog‘m should not issue an Invite Input 
to the terminal. 


If no tnvite Input is to be issued to this terminal, 
the terminal is released from the program. 


If requests from other terminals are in process or 
awaiting processing, they must be completed before 
the program terminates. The number of remaining 
requests can be determined from the count of 
outstanding Invite Inputs, returned in the third 
field of the parameter list by the previous Release 
Terminal operation. 
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Figure 3-4. Program that Communicates with Multiple Requesting Terminals and Program-Selected Terminals 
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Multiple Requesting Terminals and Program-Selected 
Terminals 


Figure 3-4 shows an example of the general logic of a 


communications program that accepts requests concurrently 


from several requesting terminals and, in satisfying the 


requests, contacts one or more program-selected terminals. 


As each requester is satisfied, the program releases it, 
enabling the requester to enter other commands to the 
CCP. The program-selected terminals in this example are 
not released from the program until! the last requester has 


been served and the program is terminated. The numbered 


notes further explain key steps in the logic. 


0 


@ 


The first-time processing required when program- 


selected terminals are used is described in Figure 3-2. 


When a program is capable of handling more than 
one terminal, it may need to set aside a separate 
work area for each. The program may have to 
retain enough information to remember what it 
has previously received from each terminal. When, 
for example, input data consists of more than one 
part, a separate routine often processes each differ- 
ent part. A complete input message might consist 
of a customer name or number, an order number, 
item numbers, quantities, prices, and other informa- 
tion, entered as separate lines of input data and, in 
fact, as separate transmissions from the terminal. 
The program must be able to determine which por- 
tion of the data it is processing, where to store that 


© 


e 


data in the work area, and which routine processes 
that portion of the data. 


When a program-selected terminal has completed a 
message sequence, the program must determine 
whether it wants to invite additional input from the 
terminal. For example, if the program has received 
an end-of-input signal or if the system operator has 
issued the SHUTDOWN command, the program 
should not issue an Invite Input to the terminal. 


If requests from other terminals are in process or 


awaiting processing, they must be completed before 
the program terminates. 
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SYMBOLIC FILES 


Under the CCP, you can write a program using a file name 
(symbolic file) which might refer to a different physical 

disk file each time the program is executed. The physical 
(actual) files must be similar in format (that is, the same file 
organization, access method, record length, key length, and 
key position), although different in content. For example, 
you could write a student report program that generates 

a report for a different school on each execution, depending 
on which school’s student file is associated with the symbolic 
file for a particular run (Figure 3-5), 






Student Report Program 


+ 


- om < 

Requesting Terminals /File command C_ ag 4 Symbolic file name 
says: “For this run, School X is IN | used in the program 
School 1” * 


Im sw 
| oes 
; ~ 
Gee Ce Ca Physical files to 
—) ee Naa which the symbolic 
Leioal 1 Schoo 3] sonoot file name may refer. 


The assignment statements for this example might look like this (see CCP System Reference Manual 
for explanations of the assignment statements): 


// DISKFILE NAME-SCHOOL1, ORG-I, RECL-100, KEYPOS-94, KEYL-7 

// DISKFILE NAME-SCHOOL2, ORG-I, RECL-100, KEYPOS-94, KEYL-7 

// DISKFILE NAME-SCHOOL3, ORG-I, RECL-100, KEYPOS-94, KEYL-7 

// SYMFILE NAME-SCHOOLX, DISKFILE-’SCHOOL1, SCHOOL2, SCHOOL3’ 
// PROGRAM NAME-STURPT, PGMDATA-NO, FILES-’SCHOOLX/DG’ 


Figure 3-5. A Symbolic File 


The specific physical file to be used on a particular run of names of one or more valid physical files are associated with 
the program is determined by the operator of the requesting the symbolic file name by means of the DISKFILE and 
terminal by means of a /FILE command prior to the program SYMFILE assignment statements (see CCP System Refer- 
request (see CCP Terminal Operator’s Guide or CCP System ence Manual). // F\LE OCL statements for the physical 
Operator's Guide for a description of this command.) The files are entered by the system operator during CCP 

startup. 
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Considerations and Restrictions in Using Symbolic Files 
@ An MRT program cannot use symbolic files. 


® On the Model 10 Disk System or the Model 12, if your 
program releases the requesting terminal prior to the 
initial opening of any symbolic file, the CCP will cancel 
your program. You must be especially careful in pro- 
grams that can be requested from the console, since the 
console is automatically released from your program by 
the CCP. 


To use symbolic files in Model 10 and Model 12 CCP 
application programs that can be requested from the 
console, you must specify at assignment time (// PRO- 
GRAM statement) that data is allowed with the program 
request, even if no data will actually be entered. The 
CCP releases the console when the first Accept Input in 
the program has resulted in the name CONSOL and 
prograrn data being passed to the user program. There- 
fore, the symbolic file must be opened before the Accept 
Input. In RPG iI all files are opened before any |/O 
operations can be performed. 


®@ On the Model 10 Disk System or a Model 12, a serially 
reusable program (COBOL or Basic Assembler) will 
access the same physical file when it is reused (executed 
without being reloaded) as it was used on its initial 
execution. 


SWITCHED LINES 


A switched fine is a communication line on which the 
connection between the system and the terminal is established 
by dialing a data set (telephone) number either automatically 
or manually. After the connection is completed, data can 

be transmitted. A terminal on a switched line is disconnected 
under control of an application program by means of the 
Release Terminal operation (see Operations, in Chapter 2). 
This operation can specify whether to keep the line allocated 
to the program or to “return” it to the CCP. 


If command mode terminals are attached to a switched 
line, the CCP awaits calls from the terminals, rather than 
polling the terminals for commands. 


Under the CCP, a data set (telephone) number can be 
established at assignment time (TERMNAME statement) 
for each terminal name assigned to a terminal that might 

be called by an application program running under the CCP. 
Also, the attribute set associated with a terminal on a 
switched line can assign the attributes auto/manual call 

and auto/manual answer. 


Auto Call 


If a terminal is defined as auto ca// by the TERMATTR 
assignment statement, an 1/O operation from a user program 
to the terminal on a switched line that is not connected 
causes the CCP to place a call to the terminal automatically. 
Auto call cannot be used with MLTA terminals. In order 

to use auto call on BSCA terminals, the Auto Call feature 
must be installed on the BSCA hardware. 


Manual Call 


If a terminal is defined as manual call by the TERMATTR 
assignment statement, an |/O operation from a user program 
to the terminal on a switched tine that is not connected 
causes the CCP to inform the system operator that he must 
dial a data set number. on a certain line. 


Auto Answer 


If a terminal is defined as auto answer, the CCP awaits a 
call from the terminal, and automatically answers the cal 
(if the auto answer feature is activated on the data set). 

An I/O operation from a user program to a switched line 
that is not connected causes the CCP to inform the system 
operator that the program is awaiting a call on the switched 
line. 


Manual Answer 


In manual answer, the system operator answers a call from 
aterminal. The system operator and terminal operator then 
place their data sets in data mode; the CCP waits for input 
from the terminal. An {/O operation from a user program 
to a switched line that is not connected causes the CCP to 
inform the system operator that the program is awaiting 

a call on the switched line. 


BSCA Switched Line 


On a BSCA switched line, the CCP allocates the line to the 
user program when the first terminal on the line is allocated. 
In order to communicate with a terminal on the line, the 
program must either already have the line allocated or the 
line must be free for allocation (not currently allocated to 
another program). 


Invite Input operations can be outstanding to multiple 
terminals on the same line after a connection has been made. 
The CCP determines which symbolic name to return with an 
Accept Input operation from the exchange identification 
characters, which are associated with a specific terminal 
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name by the BSCATERM assignment statement (see CCP 
System Reference Manual). 


Note: \f a communications operation is issued to a terminal 
for which VERIFYID—NO is specified in the TERMATTR 


assignment statement and the operation is an answer 


operation, then any terminal that calls satisfies the operation. 


BSCA Requesting Terminals 


The following examples illustrate the use of BSCA switched 


lines with requesting terminals. Assume you have the 
following switched point-to-point network: 









ID1 (TERM1) 1D1 
CcP [12 (TERM 2) | ID2 Exchange !D’s 
| User program ID2_ (TERM 2) ID3 
ID3 (TERM 3) | TERM1 
TERM2 Symbolic terminal names 
TERM3 
Common Carrier 
(telephone) 
Exchange 
Example 1: 
ID1 1. ID2 (TERM2) calls, makes connection,.signs on, 
makes a program request, and communicates with 
I 
Eregran ae program under the name TERM2. 
ID3 
2. Program issues Release Terminal operation, keeping 
the line. ID2 is signed off automatically. 
ID1 
Program ID2 3. Program now has control of the line, can call or ac- 
ID3 cept calls from 1D1, 1D2, or 1D3 in data mode. 
Note: No terminals are allowed to call in and sign on 
while the line is in control of the application program. 
Example 2: ID41 1. 1D2 (TERM2) calls, makes connection, signs on, 
makes a program request, and communicates with 
Program ID2 program under the name TERM2. 
ID3 
2. Program reaches end of job without issuing a 
Release Terminal operation. 
D1 
CCP ID2 3. TERM 2 is still connected and can enter other 
ID3 commands and program requests. 
4. TERM2 signs off specifying DROP. The connection 
ID1 to TERM2 is broken. 
ccP ID2 
1D3 5. 1D1, ID2, and [D3 can call and sign on. 
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Program-Selected Terminals 


The following examples illustrate the use of BSCA switched 
lines with program-selected terminals. Assume, again, a 
switched point-to-point network. 








Example 1 : a : 
ID1 Program issues Invite Input operations to [D1, 1D2, 
Program ID2 aneeIDS. 
ID3 {D3 calls and communicates with program as 
TERMS (Accept Input operation code). 
: 1D1 Program issues Release Terminal to TERM3 with 
CGP ID2 or without keeping the line and issues another 
Accept Input (the line is disconnected). 
ID3 
1D1 and D2 can call and communicate with the 
program; 1D3 cannot, since it no longer has an 
Invite Input. 
Example 2: : 
1D1 Program issues Invite Input operations to 1D1, ID2, 
Program ID2 and 1D3. 
ID3 1D3 calls and communicates with program as 
TERM3 (Accept Input operation code). 
ae Program goes to end of job without releasing 
CCF ID2 terminals (programs should issue Stop Invite 
ID3 Inputs to terminals with outstanding Invite 
Inputs before going to end of job). 
All Invite Inputs are cancelled; terminals are 
available to other programs, 
Example 3: 
D1 Program calls 1D2 and communicates with I1D2 as 
Program ID2 TERM2. 
D3 Program issues Release Terminal to TERM2 with 
or without keeping the line (the line is disconnected). 
1D1 Program can call 1D1, 1D2, or [D3 and issue 
CCP ID2 Invite Inputs. CCP either automatically calls 
ID3 the correct data set number (auto call) or 


provides the correct data set and line number to 
the system operator (manual call). 
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MLTA Switched Line 


On MLTA switched lines, there is only one terminal per 
line. Both the line and the terminal are allocated to the 
program by the CCP. The examples of using a switched 
line with command terminals and data terminals given 
under BSCA Switched Line apply also to MLTA switched 
lines, except that: 


®@ All terminals that call on an MLTA switched line have. 
the same symbolic terminal name; they cannot be 
uniquely distinguished from each other. 


@ MLTA terminals on switched lines do not have exchange 
identification characters associated with them. 
Switched Line Disconnect Considerations 


The CCP disconnects a terminal on a switched line in any 
of the following circumstances: 


® User program issues a Release Terminal operation speci- 
fying the keep-line modifier. 


@ User program issues a Release Terminal operation without 


the keep-line modifier to a data terminal (see index entry). 
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@ User program issues a Release Terminal operation to a 
command terminal that is not the requesting terminal. 


@ The user program terminates while the line is being used 
with a program-selected terminal. 


@ The system operator issues a VARY OFFLINE command 
to a termina] connected to the switched tine. 


@ Arequesting terminal on the line signs off (/OFF) and 
the DROP option is in effect. 


The only Release Terminal operation for which the terminal 
is not disconnected is a Release Terminal operation to the 
requesting terminal without the keep-line modifier. In this 
case, the requesting terminal is still in command mode and 
can continue to enter commands to the CCP. 


When a command terminal is connected on a switched line, 
the CCP attempts to maintain the terminal connection as 
long as possible. After a program has terminated and the 
CCP has sent the “ended” or “released’” message (which 
can optionally be suppressed by specifying ENDMSG-NO 
on the // PROGRAM assignment statement), the CCP 
attempts to receive from the terminal for an amount of 
time that is based on the error retry count specified by the 
NRETRY parameter on the // BSCALINE assignment 
statement. 


To request CCP communication services, you must write 
your COBOL programs using the standard application 
program interface described in Chapter 2. This standard 
interface is composed of the following elements: 


® Communications Service Subroutine 
@ Parameter List 
@ Record Area 


Note: This chapter assumes that you are familiar with the 
COBOL language. For more information on writing and 
executing COBOL programs, see the publications /BM 
System/3 Subset American National Standard COBOL, 
GC28-6452, and /BM System/3 Subset American National 
Standard COBOL Compiler and Library Programmer’s 
Guide, GC28-6459. 


COBOL USE OF THE STANDARD INTERFACE 


To use the standard application program interface to the 
CCP, the COBOL application program must: 


1. Define the record area and the parameter list (see 
Defining the Record Area and Parameter List). 


2. Set the contents of the parameter Jist and the record 
area (see Setting the Contents of the Parameter List 
and Record Area). 


3. Call the communications service subroutine, identi- 
fying the program’s parameter list and record area, to 
initiate the operation (see Calling the Communications 
Service Subroutine). 


4. Examine information returned by the CCP in the 
parameter list and record area and, for input operations, 
process the input data (see Examining Returned In- 
formation). : 


DEFINING THE RECORD AREA AND PARAMETER LIST 


Before your COBOL program can perform communications 
operations, you must define one or more record areas and 
parameter lists. 


Chapter 4: COBOL 


Record Area 


The number of record areas you must define depends upon 
the logic of your program. You need not always define 
separate record areas for input data and output data, or for 
operations with different terminals. 


Each record area defined must be large enough to contain 
either the program name (if a chained task), or the terminal 
name, and the maximum length of data to be either re- 
ceived as input in the record area or to be transmitted as 
output from the record area. Define the record areas in 
the WORKING-STORAGE SECTION of the DATA 
DIVISION of your COBOL program. 


The name field portion of the record area must be specified 
as an alphameric character field. In the following example, 
TERM-NAME is the name of a symbolic terminal name 
field that has been initialized to blanks: 


05 TERM-NAME PIC X(6) VALUE SPACES. 


Define the data portion of the record area as required by 
your formats. Unless you are using a BSCA line with the 
Text Transparency feature (see index entry Terminal 
Attribute), you should define all elementary data items as 
one of the following types: 


@ Alphanumeric 
@ Alphabetic (PIC A). 


® Numeric DISPLAY (PIC 9... or S9... with USAGE as 
DISPLAY or omitted). 


@® Numeric zoned-decimal (PIC 9 or S9 with USAGE speci- 
fied as COMP or COMPUTATIONAL). 


Do not define numeric data fields of the record area with a 
USAGE specified as COMPUTATIONAL-3, COMP-3, 
COMPUTATIONAL-4, or COMP-4 unless data is being trans- 
ferred over a BSCA tine using Text Transparency. 


COBOL 4-1 


Many COBOL application programs require that the same 
record areas be used for records with different formats. By 
defining each record area at the 01 level, you can redefine 
the record area with complete flexibility, using REDEFINES 
clause. (If you define record areas at another level, you 
must ensure that lengths are identical on any redefinition.) 
Because you must define the record area in the WORKING- 
STORAGE SECTION of the DATA DIVISION, rather than 
the FILE SECTION, you can assign a value to fields in the 
record area when you initially define the record area (though 
only in the original definition, when using the REDEFINES 
clause). 


Example: Figure 4-1 shows how to define a record area 
whose record may be in either of two formats; 
REC-AREA-A-2 redefines REC-AREA-A-1. The symbolic 
terminal name field is initialized to blanks. 
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Figure 4-1. Defining a Record Area 
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Parameter List 


You must also define one or more parameter lists in the 
WORKING-STORAGE SECTION of your program’s 
DATA DIVISION (see index entry parameter fist). The 
first four fields of the parameter list should be defined as 
two-byte binary (PIC S9(4), USAGE specified as 
COMPUTATIONAL-4 or COMP-4) fields. Because the 
parameter list is defined in the WORKING-STORAGE 
SECTION of DATA DIVISION rather than the FILE 
SECTION, you can also specify initial values for these fields. 
The fields are, in the sequence they must be defined in the 
parameter list: 


I. Return code field. 
2. Operation code and modifier field. 


3. Field used jointly for output data length, actual 
input data length, count of outstanding Invite Inputs, 
and attributes identifier. 


4, Maximum input data length field. 


These fields are the only fields you reference in your appli- 
cation program. The remaining four fields of the parameter 
list are not referenced directly by your COBOL program. 
However, they must be defined because space must be 
reserved for them. You can define them simply by specifying 
FILLER with a PICTURE of X(8). Your program should 
never initialize or set these fields. 


Example: Figure 4-2 shows how to define a parameter list 

in a COBOL program. The operation field is initialized to 

2 for a PUT operation. The output data length field is 
initialized to 48. This value might be the length of the first 
output message. The maximum input data length is initialized 
to 60. This value might be the total length of the data 
portion of a record area used with this parameter list. 


Return Code Values 


The CCP ignores the contents of the return code field of 
the parameter list at the beginning of a communications 
operation. At the completion of each operation, the CCP 
places a binary value in this field indicating the status of 
the operation. This value indicates: 


@ The operation completed normally (value of zero) for 
nonchained operations; value of 14 for task chained 
operations) 


@ The operation resulted in an |/O error (negative value) 


@ The operation resulted in an exceptional condition 
(positive value) 


The CCP places this value in the return code field of the 
parameter list before returning to the COBOL program. The 
COBOL program must check the return code value upon the 
completion of each operation. Specific return code values 
and their meanings are given in Appendix E. Return Codes. 


Operation Code Values 


For each communications operation, you must set the 
operation code field of a parameter list to a value which 
indicates the specific operation being requested. You must 
set this value within your COBOL program. This field can 
be set by initializing the field in the definition of the 
parameter list or by moving an appropriate value into the 
operation code field during execution (see Setting Fields in 
the Parameter List later in this chapter). 


The CCP does not change this field during the communica- 
tions operation; the contents of the field are the same after 
completion of the operation as they were at the beginning 
of the operation. See Chapter 2: Standard Application 
Program Interface to the CCP for descriptions of the valid 
operation. Appendix D: Operation Codes summarizes the 
operation code values. 
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Figure 4-2. Defining a Parameter List 


SETTING THE CONTENTS OF THE PARAMETER LIST 
AND RECORD AREA 


You must set the contents of the following areas before 
performing a communications operation in COBOL: 


1. Parameter list fields, if different from the last 
operation. 


2. Symbolic terminal name in the first six positions of 
the record area. (This can be omitted if a terminal 
name is not required for the operation or if the 
name is the same as in the previous operation.) 


3. Output data in the data portion of the record area 
if the operation is an output operation. 
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Setting Fields in the Parameter List 


You reference four parameter fields within your COBOL 
program: 


@ Return Code field. 
®@ Operation Code field. 


® Field used jointly for output length, effective input length, 
count of outstanding Invite Inputs, and attributes identifier. 


@ Maximum input length field. 


You need set only the operation code and the Maximum Input 
Length field for input operations. For output operations, you 
must set the operation code and the Output Length field. 

For an Acquire Terminal operation, you must set the opera- 
tion code and, if this Acquire Terminal also sets the terminal 
attributes, the Attributes Identifier field. You need never set 
the return code field; it is used only by the CCP to return 
information about the operation to your COBOL program. 


Operation Code 


Whenever a communications operation is issued, this field 
must contain a value indicating the operation to be performed. 
You can set this field when you define it in the WORKING- 
STORAGE SECTION of the DATA DIVISION by specifying 
a VALUE clause: 


05 PL-OPC PIC S9(4) COMP-4 VALUE 4. 


You can also set this field with a MOVE statement in the 
PROCEDURE DIVISION of your COBOL program. You 
can move either a numeric literal or a named numeric value 
into the operation code field of a parameter list you defined. 
In the following example, the numeric literal 4 (Accept 
Input operation) is moved into the operation code field 
PL-OPC: 
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The following example sets the Operation Code field by 
moving the named numeric field, ACPTIN, into it. ACPTIN 
is defined with the value 4. 
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The CCP never modifies the value in the Operation Code 
field. You do not need to reset the field if the operation 
to be performed is the same as the last operation using this 
parameter list. 

For more information on the valid operations, see the 
chapter Standard Application Interface to the CCP. 
Appendix 0: Operation Codes summarizes the operations 
and operation code values. 


Output Length/Attributes Identifier/Count of Outstanding 
Invite Inputs/Effective Input Length 


The third field of the parameter list can contain one of four 
different values depending on the type of operation: 


@ Output Length 
® Attributes Identifier 
® Count of Outstanding Invite Inputs 


® Effective Input Length 
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The first two values you must set; the third and fourth are 
returned values set by the CCP for certain operations. 


You can set this field when you define it in the 
WORKING-STORAGE SECTION of the DATA DIVISION 
by means of a VALUE clause, or in the PROCEDURE 
DIVISION by specifying a MOVE statement, just as you 
set the operation code field. You can move either a 
numeric literal or a named numeric value into the field. 


Output Length: For task chaining and output operations, 
you must place into this field the length of the data you 
wish to write from the record area in your program. This 
length does not include the six positions for the program 
name or the symbolic terminal name. The output opera- 
tions you must set a data length for are: 


@ Put 
@ Put-No-Wait 
@ Put-Then-Get 


@ Chain Task Request 


You must reset this value if the output data length differs 
from the last operation using this parameter list or if the 
field was modified by the CCP. This field is modified by 
the CCP for the following operations: 


@ Get 

@ Put-Then-Get 

® Accept Input 

@ Get Terminal Attributes 
@ Acquire Terminal 


@ Release Terminal 


Attributes Identifier: \f your operation code specifies an 
Acquire Terminal operation which sets the attributes of 
the terminal to be acquired, you must place into this field 
the identifier of the attributes set. This numeric value 
must correspond to the number you assigned to the desired 
set of attributes in an Assignment run. 


Effective Inout Length: You do not need to set this 

value. For each input operation, the CCP places the actual 
length of the input data passed to your COBOL program in 
this field before it returns control to your program. This 
is the length of the data only, it does not include the 
length of the terminal name. 


Count of Outstanding Invite Inputs: Ona Release Terminal 
operation and on any input operation that results in a 08 
return code (terminal entered data mode escape and issued a 
/RELEASE command), this field is set by the CCP to the 
number of Invite Input operations still outstanding. If this 
is a multiple requesting terminal (MRT) program, this 
number includes not only the Invite Inputs you have issued 


that have not yet been satisfied by an Accept Input operation, 


but also the number of additional terminals that have re- 
quested your program but are not yet being served by your 
program. 


Maximum Input Data Length 


For each operation involving input data, you must enter a 
numeric value into the fourth field of the parameter list, 
indicating the maximum amount of input data you expect 
to receive. This value must be greater than zero and no 


larger than the size of the data portion of the record area 
with which this parameter list is used. The value does not 
include the six positions at the beginning of the record area 
for the name field. The input operations for which you 
must place a value in this field are: 


@ Get 


@ invite Input 


Accept Input 


Put-Then-Get 
© Get Terminal Attributes 
@ Stop Invite Input (in case input cannot be stopped) 


You can set the value of this field either when you define 
it in the WORKING-STORAGE SECTION of the DATA 
DIVISION or by means of a MOVE statement in the 
PROCEDURE DIVISION. The CCP never modifies the 
value in this field. Therefore, you do not need to reset it 
unless the maximum input length for this operation is 
different from the value set in this field the last time this 
parameter list was used. However, if this parameter list 

is used with more than one record area, you may need to 
alter this value during execution of your COBOL program. 


Example of Setting Fields in the Parameter List 


Figure 4-3 shows how you can set the operation, output 
data length, and maximum input data length fields of a 
parameter list. Each operation code value is assigned a 
name. These names are then used on a MOVE statement 
that moves the named numeric values into the operation 
field of the parameter list. The output data length and 
maximum input data length fields are set by moving 
literals into them. 


Setting the Record Area 


The record area consists of a six-position name field and a 
data area. For an operation with a terminal, except for 
Accept Input and Shutdown Inquiry operations, you must 
place the symbolic name of the terminal to be involved 

with the operation in the name field. For a Chain Task 
Request, you must place the name of the requested program 
in the name field. You must also provide the data to be 
transmitted in the data portion of the record area when an 
output operation is to be performed. 
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Figure 4-3. Setting Fields in the Parameter List 
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Name Field 


For an operation involving a terminal, the terminal name 
you place in a record area must have been assigned to your 
program. You may also identify the requesting terminal by 
using six blariks as the terminal name if your program is 
not a multiple requesting terminal (MRT) program (see 
index entry). See Chapter 2: Standard Application Pro- 
gram Interface to the CCP for more information on the 
valid terminal names. 


For a Chain Task Request operation, you must provide the 
name of the program to be loaded in the name field. 


You may set the name when you define the record area in 
the WORKING-STORAGE SECTION of the DATA 
DIVISION, or by means of a MOVE statement in the 
PROCEDURE DIVISION. You do not need to reset the 
terminal name if the terminal to be used is the same that 
was named the last time the record area was used, unless 
the name was modified by CCP. CCP modifies the name 
field of the record area in the following situations: 


@ Upon completion of an Accept Input operation, CCP 
sets the name field to the name of the program or ter- 
minal whose data is placed in the record area. 


@ Upon completion of any operation using the name 
field that was set to blanks, CCP sets the name field to 
the name of the requesting program or terminal. 


Output Data Area 


If the operation to be performed is an output operation, 
you must provide the data to be transmitted in the data 
portion of the record area. You do not need to provide 
data in the record area for operations other than output 
operations because either the data area is not used or data 
is provided to your program by CCP. Data provided to 
your program by CCP overlays the information previously 
in the data portion of the data area. For example, the 
input data transmitted to your program by the Get part 
of the Put-Then-Get operation overlays the output data 
transmitted from your program by the Put part of the 
operation. See the Chapter 2: Standard Application 
Program Interface to the CCP for more information on 
transferring cata. 


Note: \f the message to be sent is shorter than the total 
length of the data area, you need not clear the excess 
area to blanks. 


Example of Setting the Record Area 


Figure 4-4 shows how you can define and set the record 

area when it is used for both input and output operations. 
Assume the CCP has set the terminal name and data area as 
the result of an Accept Input operation. The COBOL program 
then resets the data area for an output operation by moving 
the message “TRY AGAIN INV DATA” to the data portion 
of the record area. This message overlays the input data 
transmitted to the record area by the Accept Input operation. 
Later in the program, the terminal name is reset to a named 
alphanumeric value. 


CALLING THE COMMUNICATIONS SERVICE 
SUBROUTINE 


Since COBOL does not include special statement types 

for terminal I/O operations and other communications 
services, the CCP provides a communications service sub- 
routine, ‘CCPCIO,’ that converts the COBOL program's 
communications requests into a standard request to the 
CCP communication facilities. The functions performed by 
CCPCIO for the COBOL program are: 


®@ Loads index register 2 with the address of the program's 
parameter list. 


@ Places the address of the record area into the program's 
parameter list. 


@ Branches to the CCP. 


The CCPCIO subroutine must be linkage edited with the 
COBOL application program. See Chapter 9. Program 
Preparation. 


After you have set the required parameter list fields and 
the terminal name in the record area, and have prepared 
any output data, you are ready to request the CCP to 
perform the operation specified in the parameter list. 
You make this request by issuing a CALL statement 
specifying ‘CCPCIO’. The names of your parameter list 
and record area must be passed as arguments to the sub- 
routine. 


The format of the CALL statement is as follows: 


CALL ‘CCPCIO’ USING parameter-list-name, record-area-name. 
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Figure 4-4. Setting the Record Area 
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The CALL statement appears in the PROCEDURE 
DIVISION of your COBOL program. 


In the following example, the name of the parameter list 
is PARM-LIST. The name of the record area is INPUT- 
OUTPUT-AREA. 


CALL ‘CCPCIO’ USING PARM-LIST, INPUT-OUTPUT-AREA. 


Control returns to your COBOL program at the statement 
immediately following the CALL statement. When the 
return occurs, the following actions have already taken 
place: 


@ For output operations, any output data has been 
accepted by the CCP and, depending upon the output 
operation specified, has been received by the terminal. 
In any case, the record area is now free for you to use 
again. 


@ For input operations, any input data which was to be 
received in the record area is now in the record area, 
unless ari error condition or one of several exception 
conditions occurred. 


® For Accept Input operations, the name of the program 
or the symbolic terminal name of the terminal that pro- 
vided the data in the record area has been set in the 
first six positions of the record area. 


@ For successful task chain operations, the requested pro- 
gram is placed on the program request input queue when 
control is returned to the requesting program. 


® For operations that validly specified a blank terminal 
name, the symbolic terminal name of the requesting 
terminal has been set in the first six positions of the 
record area. 


© For all operations, the return code field in your parameter 
list has been set indicating the result of the operation. 


® For input operations, the actual input data length has 
been set in your parameter list. 


® For Release Terminal operations or for input operations 
where the terminal has released itself from the program, 
the count of outstanding Invite Input operations has 
been set in your parameter list. 


EXAMINING RETURNED INFORMATION 


After control has returned to your COBOL program from 
the communications service subroutine, you should examine 
returned information supplied by the CCP, including one 

or more of the following: 


@ The return code 


®@ The symbolic terminal name (if it was set by the CCP) 
or the name of the program that issued the Chain Task 
Request operation 


® The count of outstanding Invite Inputs, if a Release 
Terminal operation was performed, or if the return 
code from an input operation indicates the terminal 
was released 


@ The actual input data length, if an input operation was 
successfully performed 


@ The input data, if an input operation was performed 


Return Code 


The CCP always provides a return code after an operation. 
You should never assume that an operation is successful; 
you should always check the return code. In certain cases, 
you will find that no data transfer has occurred. See 


_ Appendix E for the meanings of specific return codes and 


see Programming Examples, later in this chapter, for 
examples of checking return codes. 


You may wish to perform certain operations in your COBOL 
program depending upon the return code value set by the 
CCP, The example in Figure 4-5 assumes. that you want to 
branch to one of several procedure names depending upon 
the value of the return code. The program examines the 
return code value for the following conditions: 


® The operation was successful and no exceptions occurred 


@ An EOT was received on a successful operation, or on 
an operation in which data was truncated. 


@ Some other exception condition occurred. 
@ An 1/O error occurred. 


Assume that all data names have been defined earlier in 
this program. Note the use of comments in the example. 
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Figure 4-6. Saving the Symbolic Terminal Name 
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Examining a Returned Name 


On certain operations, the CCP returns the symbolic terminal 
name to your program’s record area. You may need to 
examine this name. 


For example, you may need to examine the name of the 
terminal that provided the input data. You can then com- 
pare the terminal name in the record area with a saved 
terminal name to associate new data with data previously 
received from this terminal. You can save a terminal name 
for later comparison by specifying the terminal name field 
of the record area in a MOVE statement. The field to which 
the terminal name is moved must be defined with a 
PICTURE of X(6). 


The example in Figure 4-6 saves the terminal name the 
CCP sets in the name field of the record area, TERM- 
NAME-A, by moving it to the field SAV-TERM-NAME. 
SAV-TERM-NAME is the name field in a table of saved 
values. 


If a program can be requested from both a terminal and 
another program using the Chain Task Request operation, 
you may want to determine how the program was re- 
quested. This can be accomplished by checking for a 14 
return code, indicating a Chain Task Request operation. 
This information is useful if a program communicates with 
the requestor since your program cannot communicate 
with a chain task requesting program. 


Referencing Saved Information 


In some of your COBOL programs, you may need to save the 
information entered on the terminals and reference it later 

in your program. For example, if your program receives 

data from several different terminals, you may need to 
associate new data entered on a terminal with data previously 
entered on the same terminal. To do this, you must save 

the significant data received from every terminal you are 
using and identify that saved data with the name of the 
terminal from which it was received. You can then associate 
new data with the saved data by comparing the terminal 
name set by the CCP in the record area with the saved 
terminal names. 


One way you can save information received from each 
terminal is to define a table of group items. Specify the 
number of terminals from which information must be 

saved as the integer in the group item’s OCCURS clause. 
For example, if information must be saved from five termi- 
nals, specify that the group item OCCURS 5 TIMES. Each 
group item consists of a set of elementary items, one of 
which is the terminal name. Upon completion of an Accept 


Input operation, you can then search the table of saved 
information until you find the saved terminal name that 
corresponds to the name of the terminal which just trans- 
mitted data to your program. Once you have found the 
table entry you are searching for, you can address any 
field of the save information by indexing that field name 
with the index name. 


Figure 4-7 shows how to set up a table for saved information 
and reference the saved information in your COBOL program. 
By searching the table for the saved terminal names that 
corresponds to the terminal name in the record area, you 

can associate the new data with the data that was saved. 


Effective Input Data Length 


1f the communications service subroutine requested an 
operation which transferred data to your program (Get, 
Accept Input, Get Attributes, Put-Then-Get, or Stop Invite 
Input), the CCP also places the effective length of the 

input data into the parameter list. Because this is the length 
of the data that was actually received by your program, you 
may wish to use this length to control subscripted or indexed 
operations in your program. For example, you may need to 
scan the input data for a specific character or string of 
characters. To do this you must know the length of the 
input data you must scan. 


Count of Outstanding Invite Inputs 


On a Release Terminal operation or on an input operation 
where the return code indicates that the terminal released 
itself from your program, the count of outstanding Invite 
Input operations is returned to your program. You may use 
this number to determine whether your program has any 
further terminals to serve or whether it can go to end of job. 


Input Data 


If the operation requested by your program is an input 
operation that transfers data, the CCP places the input data 
received by your program in the seventh and succeeding 
positions of your record area before it returns control to 
your COBOL program. Any excess positions, beyond the 
end of the actual data received, are filled with blanks by 
the CCP, up to the maximum input length you specified 
for the operation. The data is then available for you to 

use in your program. 


COBOL 4-13 





COBOL Coding Form 


PUNCHING INSTRUCTIONS 
GRAPHIC 
DATE PUNCH 


COBOL STATEMENT 





] PAGE 


| + CARD FORM = 


—_ 


IDENTIFICATION 




































































ae 
























































E 



























































TSeRT 
ete iset— 
6 
Zz 
ral 
a 
4 

















ied 



































4} 



















































































+ 
eh es le Lc 
















































































Defines a table of 
saved values for data 
received from five 

| | different terminals. | 
The group item, SAV-ENTRY, 

consists of 6 fields. | 
These fields can be 
referenced later in 
your program. 

























































S 





































































































~[—|[-|[olel[slolelole 





Search through the table of 
saved entries for the saved 
terminal name that is the same 
as the terminal name in the 
name field of the record 


area (TERM-NAME-A). When you find 
the corresponding terminal name 
proceed to FOUND-THE-ENTRY, 


HO 























jE See Pe [| Se | | fico 






































STR LS 








I 














oe 











! 
| 
| 

















iw 









































| 
f 
| 
H | 1A 
Say 


' 


f 







































































Figure 4-7. Referencing Saved Information 
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Once you have found the saved entry you were 
searching for, you can reference the saved 
fields by indexing the field name by SAV-IX: 


Compares input record type field with 
previous record from this terminal. 


@ Updates the number of transactions field in 
the saved entry by adding the new trans- 
action from the input record. 













USING THE SYSTEM OPERATOR CONSOLE 


If you wish to communicate with the system operator 
through either the 5471 Printer/Keyboard (Models 10 and 
12) or CRT/Keyboard (Model 15), you must specify opera- 
tions as though the device is a remote terminal. You cannot 
address the system operator’s console by either the 
DISPLAY .... UPON console-name or the ACCEPT....FROM 
console-name statement. Instead of using these statements, 
you must specify either a Put or Put-Then-Get operation to 
a terminal named CONSOL. CONSOL is the only name 
that can be assigned to the system operator console. 


Your program can communicate with the system operator's 
console at any time. To receive data from the console, 
you must issue a Put-Then-Get operation, which: 


1. Transmits a message to the system operator; and 
2. Accepts a reply from the system operator. 


Control is not returned to your program until the system 
operator has transmitted input data to your program. 


The operations that can be issued to the console are: 
@ Put 

@ Put-Then-Get 

@ Get Attributes 


The console is available at all times to communicate with 

any program or to enter system operator commands. 
However, if the console requests a program, it cannot request 
another program until the first program is initiated by the 
CCP. It is not necessary, nor is it valid, to issue an Acquire 
Terminal operation to the console in order to communicate 
with it. 


Example: The example in Figure 4-8 uses the system 
operator console as the terminal for a Put-Then-Get 
operation to notify the system operator of an 1/O error. 


COBOL PROGRAMMING CONSIDERATIONS 


When writing your COBOL program, remember: 


@ (Model 10 and Model 12) You cannot use either the 
ACCEPT or the DISPLAY statements when addressing 
the CONSOL. 


@ You cannot use the Checkpoint/Restart facility of Disk 
Data Management. Therefore, your COBOL program 
cannot specify the RERUN statement. 


@ (Model 10 and Model 12 CCP} You must not issue a 
STOP literal statement. Programs running under the 
CCP are not permitted to issue halts. 


@ You should not use the APPLY CORE-INDEX clause in 
your COBOL program to create an in-storage index 
(master index) for randomly processed indexed files. The 
index is built as a result of the MSTRINDX keyword of 
the DISKFILE assignment statement (see CCP System 
Reference), therefore, if you use an APPLY CORE- 
INDEX clause, you will only add unnecessary storage 
size to your program. 


@ (Model 15) You cannot use the COBOL TRACE option 
under CCP. 


@ The DISPLAY statement cannot be used for a printer. 


3270 DISPLAY FORMAT FACILITY 


You can use the 3270 Display Format Facility (DFF) of the 
CCP to aid you in formatting and using the 3270 display. 
Chapter 8: 3270 Display Format Facility describes the 
programming requirements that are unique to using 3270 
DFF, including the unique 3270 DFF operations, additional 
information that must be placed in the record area for 
certain operations, field types that are unique to the 3270, 
and other information. 


See Chapter 8: 3270 Display Format Facility for an example 


of a COBOL program that uses the DFF to support a single 
requesting 3270 terminal. 
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Figure 4-8. Using the Console 
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PROGRAMMING EXAMPLES 


Two programming examples are explained in this section: 


Example 1 — A COBOL program that supports a single 
requesting 3270 without using the Display Format Facility. 


Example 2— A COBOL program that supports multiple 
requesting terminals. 


See Chapter 8 for an example of a COBOL program that 
uses the 3270 Display Format Facility to support a single 
requesting 3270 terminal. 


Example 1 


Figures 4-9, 4-10, and 4-11 show the flowcharts, messages, 
and listing for a sample single requesting terminal (SRT) 
COBOL program. This program transmits two messages to 
a 3270 Model 1 Display System (480 character screen). 
The first message from the program requests the terminal 
operator to enter aroom number. The program uses the 
room number as the relative record number to access a 
disk file whose records contain guest and rate information 
about the room. This information is then formatted and 
displayed as the second message transmitted to the 3270 
terminal. Figure 4-9 also shows how these messages appear 
on the 3270 terminal. 


Because this program is a single requesting terminal (SRT) 
program (see index entry) without any program-selected 
terminals, it can receive data from and transmit data to 
only one 3270 terminal. However, multiple copies of this 
program could be in main storage at the same time, each 
communicating with a different 3270 Display System. (If 
multiple copies are in core at the same time, the disk file 
must be specified as sharable during the Assignment stage — 
see index entry disk file sharing.) 


Formatting the Messages for the 3270 Display 


Because this sample program does not use the Display 

Format Facility, this sample program must set all formatting 
control characters for the 3270 display screen into the 

data portion of the record area and transmit them as part 

of the messages to be displayed. Figure 4-10 shows the 
messages and the 3270 control characters as they are trans- 
mitted to the 3270 terminal. You can find the meanings 

of each of the 3270 screen format characters shown in 

Figure 4-10 in the publication /BM 3270 Information Display 
System Component Description, GA27-3004. 


The printable control characters are set by defining them 
as part of the message in the VALUE clauses of the record 
area definition. Blanks are left in the VALUE clauses 
where the unprintable format characters will be set by 
MOVE statements later in the program. 


The unprintable format characters (hexadecimal values 

that have no corresponding printable character in 96-column 
card code) are set by first coding the hexadecima! format 
characters as decimal values and initializing fields to these 
values (PSEUDO and PSEUDO2). The fields assigned these 
decimal values are then redefined so that the COBOL program 
can access these values, which are stored in hexadecimal 
internally, as the format characters. These redefined fields 
(INSERT-CURSOR, START-FIELD, SET-BUFFER-ADDR, 
and ESCAPE) are then moved into the appropriate position 
in the message. The notes to the right of the listing in 
Figure 4-11 explain the statements used by this program 

to format the 3270 display screen. You will also find 

the comments in the listing helpful. 


Notes Concerning this Sample Program 


@ Message Mode was defined during the Assignment Stage 
for the 3270 terminal used by this program. (See 
TERMATTR statement in CCP System Reference Man- 
ual.) This eliminates the need to do repetitive input 
operations until EOT is received. 


® Torun this program using a terminal other than the 3270, 
you must remove all coding dependent on the 3270. 
This includes all screen formatting specifications and 
3270 screen control characters within the data. 


@ This program will not accept data with the program 
request. 


®@ Two different lengths are used for the output length 
field of the parameter tist because the two messages 
transmitted by this sample program have different 
length. 


® This program specifies a PUT operation and a GET 
operation using six blanks as the terminal name. The 
CCP places the name of the 3270 terminal being used 
in the terminal name field of the record area after the 
first PUT operation is performed. 
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® To keep this sample program simple, return code 


checking is kept to a minimum. You may want to do 
more return code checking in your application programs. 
For example, when you issue Accept Input you should 
check for the Shutdown Requested return code (04). 
Also, if data mode escape is allowed in the CCP system, 
programs should check for return code 08 (terminal has 
released itself from the program). It is recommended 
that each installation design its own return code checking 
and console communication routines so that a standard 
is established that is satisfactory to the installation and 
can be used by all! application programs. 


This program does not check the length of the input 
data because the terminal operator is requested to enter 
a three-digit room number. If less than three digits are 
entered, the program branches to the EXIT-DONE pro- 
cedure and the program is canceled. However, you may 
want to check the input data length in your application 
programs. 
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@ Since there are only two different screen formats used 


by this program, they are both contained within the 
program. For more complete applications, you might 
store the screen formats on disk and read them when 
they are needed by your program. 


You could also use the Get Attributes operation in this 
program. If you do not know whether the 3270 Model 1 
or the 3270 Model 2 will request the program, you can 
issue a Get Attributes operation to find out which type 
of terminal requested the program. 


\f this program were coded and specified as a multiple 
requesting terminal (MRT) program with a MRTMAX=1 
keyword on the PROGRAM assignment statement (see 
CCP System Reference Manual), multiple copies of the 
program would not be allowed in main storage at the 
same time. As the program is written, multiple copies 
could be in main storage at the same time and the disk 
file must be specified as sharable (FILES keyword of 
PROGRAM assignment statement). 


START 
-[ ENTER ROOM # _ 


1. Set up parameter list to Put-No-Wait 
a message. 
- 2, Format screen for 3270M1. 
3. Put-No-Wait the message. 
(Enter Room #.) 





1. Set up parameter list for Get. 


2. Get message (Room #). ENTER ROOM #009 








Return Code 
i =0? 





Yes 


Read disk record. (Room # is relative 
record number.) 


ENTER ROOM #009 
ROOM # - 009 
RATE - $18.50 
_NAME - JOHN DOE 
ADDR - 114 5TH AVE SW 
ADDR - STURGIS, MINN. 55101 





1. Move disk data: Room #, Rate, 
Name, Address. 

2. Format screen for 3270M1. 

3. Set up parameter list for Put-No-Wait | 
message. 

4, Put-No-Wait the message. (Room #, 
Rate, Name, Address). 











END OF JOB 


Figure 4-9. Program Logic of Example 1 (COBOL SRT Program) 
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SF — Start Field CC  — Command Code 

ATT — Attribute Character WCC — Write Control Character 

IC  — Insert Cursor SBA — Set Buffer Address 

x — Data Character BA — Buffer Address of first character 
EC  —€scape Character position in the field 






Figure 4-10. Message Formats for Example 1 (COBOL SRT Program) 
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STNO 


whe 


COON out 


- 


il 
12 


13 


14 
15 
16 
17 
18 
19 
20 
21 
22 


23 


24 
25 
26 
27 
28 
29 
30 
31 


Figure 4-11 (Part 1 of 3). 


IBM SYSTEM/3 AMERICAN NATIONAL STANDARD COBOL 


-AvesBese COBOL SOURCE 
PROCESS MAP,LIST,GODECK 
IDENTIFICATION DIVISION. 
PROGRAM-ID. SRCOB). 

REMARKS. THIS IS A SAMPLE SINGLE REQUESTING TERMINAL PROGRAM 
DESIGNED TO RUN UNDER CCP. A 3 DIGIT ROOM NUMBER 
WHOSE VALUE IS BETWEEN 1 AND 10 IS ENTERED FROM A 3270 
TERMINAL. THE ROOM NUMBER IS RECEIVED BY THIS PROGRAM, 
AND IS USED TO ACCESS A FILE WHOSE RECORDS CONTAIN 
GUEST AND RATE INFORMATION ABOUT THE ROOM. THE PROGRAM 
RECEIVES THIS INFORMATION FROM THE DISK AND FORMATS IT 
AND THEN SENDS IT BACK TO THE 3270 TO BE DISPLAYED. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-S3- 
OBJECT-COMPUTER. IBM-S3. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT GUEST-FILE ASSIGN TO DA-5444-R-GSTFILE 
ACCESS MODE IS RANDOM 
ACTUAL KEY IS GUEST-KEY. 
DATA DIVISION. 
FILE SECTION. 

REESE EEE EERE KEE EOE EE GEE EEE EEE EEREE ERE EKER EEEEEEREREKEKEEE ES EEKE 

* THIS IS THE RECORD THAT CONTAINS THE GUEST AND RATE. * 

* INFORMATION FROM THE DISK FILE. * 

KEE EKEREAEK HERE KE REA EEE RE EEKEREEEREEKEEESEREREEKEEEAREKRERERKEKEKEKEEE 
FD GUEST-FILE LABEL RECOROS ARE STANDARD 

DATA RECORD IS GUEST-REC. 
O1 GUEST-REC. 

02 RPG-DATA _—~ PIC. Xe 

02 ROOM-NMBR PIC X(3).- 

02 ROOM-RATE PIC 9999. 

02 GUEST-NAME PIC X(20). 

02 ADDR-HOME PIC X(20). 

02 ADDR-WORK PIC X(20). 

02 FILLER PIC X(2)- 

WORKING-STORAGE SECTION. 

Br ee eee Gee ee ena etree re 

* INDEPENDENT FIELOS AND CONSTANTS AND KEYS 

Tau cee cites reece ede e ecco ook occas aaa Cas RaW NNE 

77 GUEST-KEY PIC S917) COMP. 

CREASE EERE EEE EEE EEE EAKERERERERERKEEAEEEGCEKEREEHEEERERERKEESR ERK 

* THESE ARE SPECIAL HEX-DECIMAL CHARACTERS USED FOR FORMATTING * 

* THE 3270 SCREEN * 

EEA EEA RHE EARKKKEAEEKEAKERKERESEKEHKERHEEEKEKEERAEERE EEE REE EERE 

OL PSEUDO PIC 9999 COMP-4 VALUE 4893. 
O1 IC-SF REDEFINES PSEUDO. 
05 INSERT-CURSOR PIC x | 
05 START-FIELD PIC X- 
O1 PSEUDOZ PIC 9999 COMP-4 VALUE 4391. @) 
O1 SBA-ESC REDEFINES PSEUDO2. 
05 SET-BUFFER-ADDR PIC X. t 


O5 ESCAPE PIC X. 


Example 1 - COBOL SRT Program 


STATEMENT S encccccceeETDENTFON SEQ/NO S 


Oo Initialize PSEUDO using decimal values 
corresponding to the hexadecimal values 
for Insert Cursor and Start Field. These 
values will be internally represented in 
binary: 

Insert Cursor = X’13' 
Start Field = X'1D’ 
X‘131D' = decimal 4893 (see Note) 


@ Redefine PSEUDO to make the resulting 
two hexadecimal values available to be 
manipulated individually in the program. 


© Initialize PSEUDO2 using decimal values 

corresponding to the hexadecimal values 
for Set Buffer Address and Escape Char- 
acter. These values will be internally 
represented in binary: 

Set Buffer Address = X'11’ 

Escape Character = X‘'27° 

X'1127' = decimal 4391 (see Note) 


Qo Redefine PSEUDO2 to make the resulting 
two hexadecimal values available to be 
manipulated individually in the program. 


Note: The hexadecimal value to be convert- 
ed to decimal must never exceed X‘270F’, 
or the resulting decimal value will exceed 
four digits and will require a three-byte 
field. If this occurs, rearrange the order of 
the hexadecimal fields to see if it results in 

a lower decimal value. If it does not, use a 
three-byte field and place a X‘00' filler in 
the first byte. 
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LEER EEE TEER EEE EEE ER EEE REET EEE HEED EATER EEE EEE EE OE EE ESE ERE 

* INPUT-OUTPUT PARAMETER LIST * 

SEIIOIIOR I III III EI IO RA RIO OR IO I Ib 6 
32 Ol PARM-LIST. 


33 05 PL-RTC PIC $9(4) COMP-4. 

34 05 PL-oPC PIC $9(4) COMP-4 VALUE 54. 

35 05 PL-OUTL PIC S$9(4) COMP-4 VALUE 26. 

36 05 PL-INL PIC $914) COMP-4 VALUE Li. 

37 05 FILLER PIC xX(8). 
PEARS EEE EEE EEE ERE EEE EEE EEE EE EEE EEE EEE ESTE EEE 
* THIS IS THE INPUT/QUTPUT AREA * 


Return Code Field 

Operation Code Field 

Output Length Field 
Maximum Input Length Field 
Required CCP Work Area 


Terminal Name Field 


RE RAE EEE EE EEE EEE EE EEE EE OE 
38 01 INPUT-OUTPUT-AREA. ee 
39 05 I-Q-TERM PIC X{6) VALUE SPACES. Data area for Messages: Initialize the con- 


40 05 I-0-AREA. 
41 10 MSG1 








PIC x(21) VALUE ' 5G ENTER ROOM # I'. 





42 10 ROOM-NUM PIC X(3) VALUE SPACES. 

43 10 CHRS1 PIC X(5) VALUE * O- $'. 

44 10 CHRS2 PIC 99.99. 

45 10 NAME PIC X(10) VALUE * ASNAME - ', 

46 10 NAM-CHR PIC X{20) VALUE SPACES. 

47 10 AODR1 PIC X(LO) VALUE * B-ADOR - ', 

48 10 AOL-CHR PIC X(20) VALUE SPACES. 

49 10 ADDR2 PIC X(10) VALUE * CHADOR - 'o 

50 10 AD2-CHR PIC X(20) VALUE SPACES. 

51 05 I-O-CHARS REDEFINES I-O-AREA. 

52 10 I-O-CHAR PIC X OCCURS 124 INDEXED BY INDX. 

53 O05 1-Q-AREA2 REDEFINES I-O-AREA. 

54 10 ROOM PIC X(15). 

55 10 ROOM-NM PIC X(3). 

56 10 RATE PIC X(8). 

57 10 FILLER PIC X(98). 

58 O5 INPUT~AREA REDEFINES I-O-AREA. 

59 10 DEVICE PIC X. 

60 10 CNTRL-U PIC X. 

61 10 AID PIC X. 

62 10 CRS-ADD PIC X(2). 

63 10 SBA PIC X. 

64 10 SBA-ADD PIC X(2). 

65 10 RM-NUM PIC XK(3). 

66 10 FILLER PIC XK(113). } 
SRRREDEEEEEEEEREEEREEEEEREEREEES EEKKESEEKE REE EEA REE ERE ERED ESSERE 
* NOW BEGIN EXECUTION BY OPENING THE DIRECT ACCESS FILE * 


REE EREREKERRERERREKEREREREKESEREEEERREEEREREEEEEESE EEE EEE ERE 
67 PROCEDURE DIVISION. 
68 OPEN-THE-FILE. 
69 OPEN INPUT GUEST-FILE. . 
EAEEEEEAREREREEAE REE EEEEEEEERSEEEEESEREEE EERE REE REE EE EES ERO SH EAE 
* INSERT THE HEXADECIMAL CONTROL CHARACTERS INTO DATA STREAM * 
EERE E EERE ERE EERES EEREREEAEEEREEREECEE EERE REE EEE EEE EE EESE EEE EEEERE 
70 FIRST-CHARS. 


71 MOVE ESCAPE TO I-O-CHARI(L). 

72 MOVE SET-BUFFER-ADOR TO I-O-CHAR(4). 

73, NEXT-CHARS. 

14 MOVE START-FIELD TO I-O-CHAR(19). 

75 MOVE INSERT-CURSOR TO I1-O-CHAR(21). 
HRA IA A AA AR RTC RB BE BIRR RR ROE 
* THIS FIELD 1S DEFINED TO PREVENT DATA FROM BEING ENTERED * 
* BEYOND THIS POSITION ON THE SCREEN. * 
SIERO III TOO OR RI IIE AIOE 

76 MOVE START-FIELD TO I-O-CHAR(25). 
FER ORI IIE BIO ICICI IOI OIE BFR 
* 00 PUT MESSAGE NO WAIT OPERATION TO 3270 TERMINAL * 
* REQUESTING THE ROOM NUMBER BE ENTERED * 


MERE EAR AER EKER EEE ERE EEE EERE ERARESEEEEEREREREREEEREEE 


Figure 4-11 (Part 2 of 3). Example 1 — COBOL SRT Program 
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tents of message fields to be displayed and 
of any printable 3270 formatting charac- 
ters. Leave blanks for any unprintable 3270 
control! characters (characters that cannot 
‘be represented by a character in the COBOL 
character set). The blank fields are set by 
MOVE statements later in the program. 

The first half of this definition is used for 
the first message; the second half is used 
only for the second message. The first part 
of the second message will be added later 
by overlaying the first message. 


Redefine the data area with an index so 
each position in the area can be referenced 
separately. 


Redefine the data area to set up the first 
part of the second message. 


Redefine cata area for Get operation. 


Move the hexadecimal values for the remain- 
ing 3270 formatting control characters to 
appropriate positions in the data area. These 
characters are unprintable. 


77 


78 
79 


80 


82 


84 


87 
89 


90 


98 


100 
101 
102 


103 
104 


105 
106 
107 
108 


CALL *CCPCIO*® USING PARM-LIST, INPUT-OUTPUT-AREA.~ 
SEO TO IOI I OIG IO IIIA IOIOIOIIEIOII IIS IE III 
* DO GET OPERATION FROM 3270 TERMINAL AND OBTAIN ROOM NUMBER * 
PAE REE RR ER EOE ATES RHEE EEE ERE HERES ES SHEERS 
MOVE 1 TO PL-OPC. 
CALL "CCPCIO* USING PARM-LIST,s INPUT-OQUTPUT-AREA. 
SARA RRA GARR AR EEE OEE HERE EE EERE EEE ASAE OST E EES ERE ES 
* IF THE RETURN CODE IS NOT ZERO GO TO ENO OF JOB * 
SIGIR IOI III IRA II IO IOC I III HIER EEE AA EE 
IF PL-RTC NOT = O GO TO EXIT-DONE. 
BR MA I HR RR ERR EE HE ERS AE EEE EE EEE EERE 
* CHECK TO SEE IF THE ENTER KEY WAS PRESSED, IF IT WAS NOT GO * 
* TO END QF JOB. * 
SA EAT REE AEE EEA EE EE EEE EERE RE EE EEE EERE EERE ER EEE 
IF I-O-CHAR(3) NOT = QUOTE GO TO EXIT-DONE. 
AES I AIG A IRI OR $8 Ri aOR RI ae 
* VALIDITY CHECK THE ROOM NUMBER IF ROOM NUMBER BAD GO TO END * 
* OF JOB * 
RI ARR EE ERE EER EEA REE AT EE TEES EEE EER EEE EE EEE EE EEE 
MOVE RM-NUM TO GUEST-KEY. 
IF GUEST-KEY LESS THAN 1 GO TO EXIT-DONE. 
IF GUEST-KEY GREATER THAN 10 GO TO EXIT-DONE. 
MOVE RM-NUM TO ROOM-NM. 
FIER OO ICR AR RI IO RIO AOR RIOR AAI RAMEE SE EET E SESE EE 
* READ RECORD FROM DIRECT ACCESS FILE. THE ROOM NUMBER * 
* REPRESENTS THE RELATIVE POSITION OF THE RECORD IN THE FILE® 
REO Ti I oR I IO I IOI IOR IO $d 408 a AOR IO 
READ GUEST-FILE INVALID KEY GO TO EXIT-DONE. 


[CRE REREER EE ERERE REESE EEE OEREREE ER OHSAS EEO EEE EE EES EEE ES BEES REE ES 
* MOVE THE ROOM NUMBER, RATE PER DAY, THE NAME AND ADDRESS OF * 
* THE GUEST INTO THE OUTPUT AREA * 
ADE HARE AEE EEE EERE OE EERE S EEE EEERE ES EERE EE EEE EEE EEE ES 

MOVE * 1G YROOM # - ' TO ROOM. 

MOVE * AGRATE *§ TO RATE.~ 

MOVE GUEST-NAME TO NAM-CHR. 

MOVE ROOM-RATE TO CHRS2. 

MOVE ADDR-HOME TO ADI-CHR. 

MOVE ADDR-WORK TO AD2-CHR. 
REE UEREREREERABKEEE ERE CECE EEE EEERREBEE SEES EERE EE EEEEEEREEE ESF EUEES 
* INSERT THE HEXADECIMAL CONTROL CHARACTERS INTO OATA STREAK * 
HEAR ERE EEE EEE EEE AKER EEE ERE EES EREDAR EE GEES ED EEOEEEREDERE SEEDED 

PERFORM FIRST-CHARS. 

MOVE SET-BUFFER-ADDR TO I-G-CHAR(19). 

MOVE SET-BUFFER-ADOR TO I-O0-CHAR(35).~ 

MOVE SET-BUFFER-ADDR TO I-O-CHAR(65). 

MOVE SET-BUFFER-AODR TO I-O0-CHARI95). 
RAR AR MR OR EEE EE HEE EET EERE SEEKER EE EEE EEE SESE SE 
* SET UP PARAMETER LIST FOR A PUT MESSAGE NO WAIT * 
CHERRIES ER EE EEE EEE EEE EEE EAE ERE E REE EEE EHH EEN EEE GEE ESTE ES 

MOVE 54 TO PL-OPC. 

MOVE 124 TO PL-OUTL. 
EAHA EEE ET ER EEE EERE EEE AE ERTS EEE RE EEE EEE EE EE RET EE EES 
* DO PUT MESSAGE NO WAIT OPERATION TO THE 3270 TERMINAL * 
HAAR ARI AA EE OR TA EEE EE OE TEER EEE TREE ES EE EE EEE 

CALL *CCPCIOt USING PARH-LIST, INPUT-QUTPUT—AREA. 

EXi T-DONE. 
CLOSE GUEST-FILE. 
STOP RUN. 


Figure 4-11 (Part 3 of 3). Example 1 — COBOL SRT Program 


Move the message, data, and printable 3270 
control characters for the first part of the 
second message into the data area of the 
record area, overlaying the first message. 


Move the hexadecimal values for the 3270 
formatting control characters that are not 
already set in the data area into the appro- 
priate positions of the data area. These are 
the unprintable control characters. 
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Example 2 


Figures 4-12, 4-13, and 4-14 show the flowchart, input/ 
output messages, and listing for a sample COBOL multiple 
requesting terminal (MRT) program designed to run under 
the CCP. This program handles up to four MLTA re- 
questing terminals. The terminal operator enters a seven- 
digit number preceded by a+, -, or N. The CCP transmits 
this signed number to the COBOL program. The COBOL 
program: 


@ Adds the number to the value in the accumulator field 
associated with the terminal that transmitted the data 


if the first position is + 


@ Subtracts the number from the accumulator if the first 
position is - 


@ Releases the terminal if the first position is N 
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If a value was either added or subtracted, the new value 
accumulated for the terminal is inserted into the message 
CURRENT VAL = sxxxxxxxxxx ENTER DATA and the 
message is sent to the terminal. 


This sample program also checks for several error conditions 
and transmits the appropriate error message to the terminal. 


This sample program is not designed to show the most 
effective way of performing operations. Instead, it shows a 
variety of ways to do things. It uses a variety of operation 
codes that show how data can be associated with a terminal 
by defining a save area for the terminal names and accumu- 
lated data. It frequently checks return codes; but you can 
do even more return code checking if you wish. Data 
entered by the terminal operator must be fixed length. To 
allow variable length input fields, you could include a sub- 
routine in your program to check the effective input length 
returned in the parameter list and align the data correctly. 
This program communicates with the console in addition to 
the requesting terminals. 


The notes to the right of the listing in Figure 4-14 and 
the comments in the listing explain each section of the 
sample program. 


~ Set up parameter 
list for Accept 
Input 

. Accept Input 






C2 
ot SAT 
Shutdown Yes 
request 0 
No 


D3 
D1 






Add terminal to 
attached list 






Terminal No 
attached 


Terminal 
cancelled 


/\ 


Yes er Yes 
E41 E2 
Terminal Yes Set cancelled 
cancelled switch 


No a) 


Negative 
return code 


Ce 


PA 


Fi 


1. 







G2 
G1 1. Set up Put-No-Wait 
Positive return (Message) (+) 
code (#0) 2. Issue Put 
No 
H1 
Operator = N 


ce & 


Figure 4-12 (Part 1 of 3). Program Logic of Example 2 (COBOL MRT Program) 








. Check input 
length =8 
2. Check valid 

operator 
. Check valid data 







c4 No 1. Set up Put-No- 


Wait (Message) 
2. Issue Put 


Vatid input 





Yes 


Find proper 


accumulator 





Add or subtract 
input to 
accumulator 










. Move ‘’-” to out- 
put area 

2, Make unit position 

printable 





G4 
1. 





Set up Put, Wait 
message 
2. Put message 








H4 
Return code 
=0 


Yes 2 


1. Set up Invite Input 


2. Invite input 
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Console routine 





Retry = 
try again 






na 
12 


-- {Release Terminal 









Terminal 
cancelled 








1. Set up Release 
Terminal op. 
2. Release terminal 






Return 
code = 0 









End of job 









. Clear terminal 
name entry in 
attached list 

. Clear accumulator 






Figure 4-12 (Part 2 of 3). Program Logic of Example 2 (COBOL MRT Program) 
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Retry = try 
again 













1. Set up Put-No- 
Wait (Message) 


Issue Put 





2. 





Shutdown Routine 
Al 


( ENTER 


Bi 


Set index = 1 


C1 










Check entry in 
attached list 


Bt Yes 
< Entry blank 


E1 No 


1. Set up Stop 
invite Input Op 
2. Stop Invite Input 


. Set up Put-No- 


ef ‘No Wait (message) 
< Terminal cancelled . Issue shutdown 
message 


Yes 


‘i (11) 
Yes 


< Effective input 
length =0 






Add 1 to index 


Index =5 


K1 


( End of job 


Figure 4-12 (Part 3 of 3). Program Logic of Example 2 (COBOL MRT Program) 





Console Routine 


B4 


ENTER 


. Set up Put-then- 
Get to console. 

2. Issue Put-then- 

Get 


















Retry = TA 
(try again) 





Set on release 
terminal indicator 





E4 


RETURN 
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Input Data Entered by Terminal Operator 


A fixed length numeric field where S is a+, —, or N and 
X isa numeric digit. All eight postions must be entered, 
except when N is entered in the first position. 





Data Entered by System Operator on 5471 Printer/Keyboard (Models 10 and 12) or CRT/Keyboard (Model 15) 


In response to the messages INPUT TP ERROR TNAME- 
cecccc and OUTPUT TP ERROR TNAME-cccccc to the 
console, the system operator replies TA if he wants to 
try again. Any other reply (cc) causes the terminal to be 
released. 





Output to the Console 






9 1011121314151617 187 1.22 23 24 25 26 27 28 29 


EIRielo el-lciclcicielc! | | 






These messages are transmitted to the console (cccccc = 
terminal name). 





EIRROIR) TINIAIME!-|CCICICIC'C 

















Transmitted with value in accumulator associated with 
the terminal. 








Issued if data is invalid. 











Issued if system operator replies TA (negative return 
coce on Accept Input). 
Issued for negative return code on Stop Invite Input. 




















Issued for positive return code other than 10 on Stop 
Invite Input. 


Issued for return code of 0 on Stop Invite Input. 























Issued for return code of 10 on Stop Invite Input 




































































Figure 4-13. Input and Output Message Formats for Example 2 (COBOL MRT Program) 
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STNO 


1 
2 
3 


WBNAWNS 


10 


IBM SYSTEM/3 AMERICAN NATIONAL STANDARD COBOL 


“Aeee8eee COBOL SOURCE 
PROCESS MAP,LIST 
IDENTIFICATION DIVISION. 
PROGRAM-ID. MRCOB1. 
REMARKS. THIS IS A SAMPLE MULTIPLE REQUESTING TERMINAL PROGRAM 
DESIGNED TO RUN UNDER CCP. A NUMBER CONSISTING 
OF UP TO 7 NUMERIC CHARACTERS AND A + OR - OPERATOR IS 
TRANSMITTED TO THIS PROGRAM BY ANY ONE OF UP TO 4 
TERMINALS. THE + OR - OPERATION IS PERFORMED AND THB 
RESULTS PLACED IN THE ACCUMULATOR ASSOCIATED WITH THE 
TERMINAL THAT REQUESTED THE OPERATION. THE VALUE IN THE 
ACCUMULATOR IS THEN SENT BACK TO THE TERMINAL FOR 
DISPLAY. IF AN N IS ENTERED AS THE OPERATOR THE 
TERMINAL WILL BE RELEASED. IF THIS IS THE ONLY TERMINAL 
LINKED WITH THE PROGRAM, THE PROGRAM WILL END 
EXECUTION. 
ENVIRONMENT DIVISION, 
CONFIGURATION SECTION. 
SOURCE-COMPUTER, IBM~S3. 
OBJECT-COMPUTER. IBM-S3. 
DATA DIVISION. 
WORKING- STORAGE SECTION. 
FORO ORI KIO RO RK IO IO IR I ROR Bk gb aoe RE 
* INDEPENDENT PIELDS AND CONSTANTS * 
FRR OI RIOR IO IORI FO III I ORO IR RIOR II AOR IG iO 2S I IO $f 
77 SWITCH PIC 9 COMP-4. 
SOI RII OIG FOR IOI IORI ROR III ROR FOR RI TOK KORO RK 
* OPERATION CODES 
FIO RR OI II III IOI OO IR OR GGG UI IGOR I OIOIGIOR 3.3901 IR EE 
77 ACPTIN PIC S9(4) COMP-4 VALUE 4. 
77 PUTNWT PIC $9(4) COMP-4 VALUE 54. 
77 PUTMYT PIC S9(4) COMP-4 VALUE 50. 
77 INVINP PIC $9(4) COMP-4 VALUE 5. 
77 PUTGET PIC S9(4) COMP-4 VALUE 3, 
77 RELTRM PIC S9(4) COMP-4 VALUE 10. 
77 STPINV PIC S9{4) COMP-4 VALUE 1025. 
FRI IOI IOI IORI IRR RIOR IRR RO OR AOE ERE EE EE 
* TERMINAL DATA STORAGE ARRAY * 
HORROR RR IR KO RIOR FOR OR RE EO HOR TK EER ERK EE EERE REE EEE 
01 TERMINAL-STORAGE-ARRAY. 
05 TERMINAL-ENTRY OCCURS 4 INDEXED BY TERM-X. 
10 TERM-NAME PIC X(6). 
10 ACCUMULATOR PIC S9(11) COMP. 
ACI IOIIIOIOIIGIOIOI III OIG ICIGO OI IORI ORI RINE RE 88 EF HE 
* COMMUNICATIONS AREA * 
*  CCP-COBOL INTERFACE PARAMETER LIST 
SOIR IORI OI RIG III IOI IOI ICI IO IO IORI IIR I IO IOI OR AOR a 


01 PARM-LIST. 


05 PL-RTC PIC $9(4) COMP-4. 
05 PL-OPC PIC $9(4) COMP-4. 
05 PL-OUT PIC S9{4) COMP-4, 


05 PL-EFL REDEFINES PL-OUT PIC S9(4) CONP-4. 


05 PL-INL PIC S$9(4) COMP-4. 

05 FILLER PIC X(8). 
ROR ORR FOI IORI SOR OR IR HII ORO FOR RRO ERE AOR OR EH REE EK EE EEE 
* THIS IS THE INPUT OUTPUT AREA * 


SOIC IGRI IO RAC IO IOI IO IG RIG OO iO fOk R EE 
01 INPUT-OUTPUT-AREA. 
05 TERM-NAME-IO 
05 DATA-IN. 






10 OPERATOR Pic xX. 
10 DIGITS PIC 9(7) COMP. 
10 FILLER _ PIC K(26). 
05 DATA-IN1 REDEFINES DATA-IN. 
10 DATA-REC PIC X(8). 
10 FILLER PIC X (26). 


05 DATA-OUT REDEFINES DATA-IN. 
10 DATA-CHAR PIC X(34). 
05 ACCUM-OUT REDEFINES DATA-IN. 
10 FILLER PIC X(12). 
10 ACCUM-VALUE PIC +t#teeeete9, 
10 FILLER PIC X(11). 
05 MSG-DATA REDEFINES DATA-IN. 
10 MSG-DATA1 PIC X(22). 
10 MSG-DATA2 PIC X(8). 


10 FILLER PIC xX(4). 


05 \MS-DATA REDEFINES DATA~IN. 
10) ~=MS~DATA1 PIC X(6).- 
10 MSS-DATA2 PIC X(17). 
10 MS-DATA3 PIC X{6). 
10 FILLER PIC X(5). 

05 TRY-AGAIN REDEFINES DATA-IN. 
10 «TA PIC xX (2). 
10 FILLER PIC X(32).: 


Figure 4-14 (Part 1 of 5). Example 2 — COBOL MRT Program 


\ 


| 


a rE 


STAT EM ENT S seoeeeeessTDENTFCN SEQ/NO S 


Define a symbolic name for each operation 
used in this program. These names are used 
in the procedure division instead of the 
numeric operation code values. 


Set up a save area for the four terminals 
used by this program and their accumulators. 


Return Code Field 
Operation Code Field 
Output Length Field 
Input Length Field 
Required Work Area 


Terminal Name Field 


The data portion of the record area is first 
defined for an eight-position field whose 
first position is for the operator (+, —, or 
N). [tis then redefined for output and 
various Messages. 


COBOL 4-29: 


65 
66 


68 


69 


70 


90 


92 
93 


95 
96 
98 
100 
102 
104 
106 


108 
109 
110 
111 


LEER EERE RR RE RTE ERK EE REA EERE EE RRR EEE CER EEE EERE ERR ER EE 
* INITIALLY SET UP THE TERMINAL ARRAY IN ORDER THAT THIS * 
* PROGRAM BE RE-ENTRANT * 
aR SRR OR ek OR OR OE EE RK EEE EER ERE ERE EK 
PROCEDURE DIVISION. 
INIT. 
SET TERM-X TO 1. 
LOOP. 
NOVE ZEROES TO ACCUMULATOR (TERN-K) © 
MOVE SPACES TO TERM-NAME (TERM-X) . 
SET TERM-X UP BY 1. 
IF TERM-X LESS THAN 5 GO TO LOOP. 
RO RE EE EEE EEE ERE EE EEE EEE REE EEE EKER EE EEE EEK EKERK ER 
* SET UP PARAMETER LIST FOR ACCEPT INPUT OPERATION * 
RARER EEE EER ERE EK ERE EE EKER EEE EEE EEE EEE EEK EEE EERE ERE EEK EREEEKEK 
ACCEPT-INPUT. 
MOVE 0 TO SWITCH. 
MOVE ACPTIN TO PL-OPC. 


MOVE 8 TO PL~INL.—-———————__—_ 
ee RR a OO EE RK EERE RARE KEKE EE EKEE REE ERE 
* DO ACCEPT INPUT OPERATION * 
HO KK RE EEE EERE RE KEE EEE EKER EEE EE EEK EEE KE EEK 

CALL 'CCPCIO' USING PARM-LIST, INPUT-OUTPUT-AREA. 

OK ERK KEKE ER ER EE EK ERE KEKE EER EEK EEK EERE EEEE EERE EERE REE 
* CHECK TO SEZ IF SHUTDOWN HAS BEEN REQUESTED * 
BR KE KK RRR HEHE ER EERE EERE AEE EKA EEK EEE EEE ERE EERE EER 
IF PL-RTC = 4 GO TO SHUTDOWN. 
ERK EO RE ROE EK ERO ERK RE KE ERK EEE EEE EE EK ERE 
* DETERMINE LP TERMINAL HAS ALREADY BEEN ATTACHED, IF IT HAS * 
* GO CHECK THE RETURN CODE * 
RK KER EEE EERE KEE EEE KEK ECEEEE EKER EEEEKERERER ERE EERE KEE EEE EEK 
SET TERM-X TO 1. 
TERN-SEARCH. 

IF TERM-NAME-IO = TERM-NAME(TERM-K) GO TO TERM-FOUND. 

SET TERM-X UP BY 1. 

IP TERM-X LESS THAN 5 GO TO TERM-SEARCH. 

PEPE TICE LS SE SELES TESTS TET EEE TESTES TST TLE SCTE SSC ESSERE TT ETT TET ES Si 





* CHECK TO SEE IP THE TERMINAL HAS BEEN CANCELED, IF IT HAS * 
* RETURN TO ACCEPT INPOT [LF NO INVITE INPOTS ARE OUTSTAND- * 
* ING. IF INVITES OUTSTANDING GO TO ACCEPT INPUT. * 


BKK EKER ER EK ERE EEK EER EH EEE KEK EEK EEE ERK ERE ROR REE EEK 
IF PL-RTC NOT = 8 GO TO ADD-TERM. 
IF PL-EFL = 0 GO TO DOWE-EXIT. 
GO TO ACCEPT-INPUT. 
ADD-TERM. 
RRA KKK ERE RHEE ERK EER EERE RRR RAE REE EK EEE KEE EKER EK E 
* ADD TERMINAL NAME TO ATTACHED LIST IF NOT ALREADY PRESENT. * 
* LOCATE & BLANK 6 CHARACTER TERMINAL NAME SPACE IN THE * 
* TERMINAL DATA STORAGE ARRAY * 
RH KK RK RO RR KK EEK RAHA E REE RE KEE EEE EEE 
SET TERM-X TO 1. 
BLANK- SEARCH. 
IF TERN-NAME(TERM~X) NOT = SPACES 
SET TERN-X UP BY 1 


GO TO BLANK~SEABCH. 
SII IOI IRR FURIOUS OI IIE IIR IIR 2 EE 


* NOTE: NO MORE THAN 4 TERMINALS WILL BE ALLOWED TO * 
* COMMUNICATE WITH THIS PROGRAM IF ASSIGNMENT SPECIFIES * 
* 4 TERMINALS * 


SONI IOIS III IOI III IOI IR HORII III IO BOR IOI IOI II IK Fok 908 FOR ICE 
MOVE TERM-NAME-IO TO TERNS-NANE (TERM-X). 
GO TO VALIDITY-CHK. 
SP RERERREREEHEREREEEER ERED ER EEE HEE ES EER TES OEE RENEE OEE ENE EEE EEE 
* CHECK TO SEE IF TERMINAL HAS BEEN CANCELLED. IF IT HAS AND * 
* THERE ARE NO INVITES OUTSTANDING GO TO EXIT. IF THERE ARE * 


* INVITES OUTSTANDING GO REMOVE FROM ACTIVE TERMINAL ARRAY. * 
EEREREEEER EEE AEERE SEER SEES EES EEEEE RECO SE OEE EEE EEE EE SEE EE EEE EEE 


TERM-FOOND. 

IF PL-RTC = 8 GO TO CANCEL-CBK. 
SAREE REREREEEEKEE EERE REE ERE ERE AE ER ERE REAR EERE EEE EEE EEE 
* CHECK FOR INPOT ERROR INDICATIONS, ISSUE ERROR MESSAGE IP * 
* RETURN CODE NOT = 0, OR IF LENGTH NOT WITHIN BANGE * 
* CHECK FOR VALID OPERATOR, IF OPERATOR EQUAL TO W GO RELEASE * 
* TERMINAL * 


EEE EERE ENED EE EERE EERE EEE ERE REESE SEER RE EE EERE EEE EEE 
VALIDITY-CHK. 
IF PL-RTC LESS THAN 0 GO TO PUT-GET. 
IF PL-RTC GREATER THAW 0 GO TO INVALID-DATA. 
IF OPERATOR = 'N* GO TO CANCEL-CHK. 
IP PL-OUT NOT = 8 THAN GO TO INVALID-DATA,—~ 
IF OPERATOR = *+' GO TO ADD-ACCUM. 
IP OPERATOR = '-' GO TO SUB-ACCUN. 
KEELER EEE REE EEE EERE ERE AEA EE EAE EAE E EE EEE EEE EEE ERE EEE 
* ASSUME BAD OPERATOR, ISSUE INVALID DATA MESSAGE * 
EEE EERE EEE EEE RE ER EE EERE EERE EKER ER KEE EER ER EERE RE EEE ERE EEEEE EER EK 
INVALID-DATA. 
MOVE "TRY AGAIN INV DATA' TO DATA-OUT, 
MOVE 18 TO PL-OUT. 
GO TO PUT-NO-WAIT. 






Figure 4-14 (Part 2 of 5). Example 2 — COBOL MRT Program 
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Initialize the accumulators to zeros and the 
terminal name save areas to blanks. 


Set the value for the accept input operation 
in the operation code field of the parameter 
list. 


Set the input field Jength to 8, the length of 
the expected input. 


Determine if the terminal name for the 
terminal that transmitted the input data is 

in the terminal name save area. If it is, the 
data is added to the value in the accumulator 
associated with that terminal. If it is not 

in the save area and the terminal is not 
cancelled, the terminal name is added to 

the save area. 


If the terminal name is not already in the 
terminal name save area, it is moved to the 
first blank terminal name field in the save 
area. 


If the return code is not equal to 0, indicat- 
ing a successful operation, or if the input 
length field is not equal to 8, an error 
message is transmitted to the terminal, 


If the first position of the input field is 

+, the data is added to the accumulator 
associated with the terminal that transmitted 
the data. If the first position is ~, the data is 
subtracted from the terminal. !f the first 
position is N, the terminal is checked to see 
if it is cancelled. 


If the first position of the input data is not 
+,-, or N, a message is transmitted to the 
terminal. 


112 
113 
114 


115 
116 


V7 
118 
119 


120 
121 


122 


123 
125 


126 
127 
128 


129 
130 


[PRR EE EERE EE EER EEE ERE EERE EK ERAT AREER EERE ES EEE ER EER REESE EEE 


* NOW ADD THE VALUBZ RECIEVED AS INPUT TO THE VALUE IN THE * 

* ACCUMULATOR * 

RRO ROE SOR ROK KEE RE EEE EE EERE EEE EEE EE REESE EEE EERE EEE 
ADD-ACCUM. 


ADD DIGITS TO ACCUMULATOR (TERMN-X) . 


GO TO DISPLAY-ACCUR. 
ATA OE POR KEE EE EES EER EE EEE EERE TEES EEE EERE SH EE EEK 


* SUBTRACT THE VALUE RECEIVED AS INPUT FRO THE VALUE IN THE * 


* ACCUMULATOR * 
ARR NE AEE EEE EEE EEE SORE EEE SERRE EERE EEE EE 
SUB-ACCOM. 


SUBTRACT DIGITS PROA ACCUMULATOR (TERM-X). 
2H He eR EEE EEE EEE EEE EEE EEE EEE EEE EEE 
* SET UP TO DISPLAY THE BESULTS RESIDING IN THE ACCUMULATOR * 
* TO THE TERMINAL THAT REQUESTED THE OPERATION * 
MAN EE EEE EE EEE EEE EE EE RERERREE EERE RERERE EERE EEE EE EE 
DISPLAY-ACCUM. 

NOVE *CURRENT VAL=+ ENTER DATA’ TO DATA-OUT.. 

MOVE ACCUMULATOR (TERM-X) TO ACCUN-VALUE. 
EGE EER EEE EER ERE EEK EE HEELS ERE EEREREKEEEKKEREECSE EEE EEE 
* SET UP PARM-LIST FOR PUT MESSAGE WAIT * 
MAR DOR DEE EEE EEE EEE REESE KER EEE EE REE REECE REEE REE RE EEE EOE ERE EERE 

MOVE PUTHWT TO PL-OPC, 

MOVE 34 TO PL-OUT. 
PEER REE EERE EEE EER EEE EERE KEE RR IRE ERE EE EEK ERK EE ERE EEK EE EEE 
* DO PUT MESSAGE WAIT OPERATION * 
RRA RRR OR EE RK EERE KER ER EE EEE EE EERE RE REE EEE EEE 

CALL *CCPCIO' USING PARM-LIST, INPUT-OUTPUT-AREA. 
ORR OR RRR ROR ORRICK EEE ERE EERE EEE 
* CHECK RETURN CODE TO SEE IF OPERATION WAS SUCCESSFUL, IF * 
* RETURN CODE NOT EQUAL TO 0 GO ISSUE ERROR MESSAGE * 
RR RRR HE SHON OR HK RR A ROR A EEE KEKE EEE EEE EEK EEK 

IF PL-RTC NOT = 0 MOVE 6 TO SWITCH 

GO TO PUT-GET. 

FRO IOU IOI IOI II IIIIOISIIOI IIR IOIOR III ION AOR ake 
* SET UP PARAMETER LIST POR INVITE INPUT * 
RHR RO RR RI RT OAR A EE OR EE KE EEE 
INVITE-INPUT. 

MOVE INVINP TO PL-OPC. 

MOVE 8 TO PL-INL. 
FRR ORR IO IOICIIOR IORI RIOR II IIIIOIO IORI II UR IR SOIR OI I IO 
* pO INVITE INPUT OPERATION * 
III IRR FOR ROTOR IR OR SII FORO RE TORE EEE EEE EEE EEE EEE 

CALL 'CCPCIO* USING PARM-LIST, INPUT-OUTPUT-AREA. 

GO TO ACCEPT-INPUT. 


Figure 4-14 (Part 3 of 5). Example 2 — COBOL MRT Program 


Insert accumulated value associated with 


COBOL 


the terminal in the output message and dis- 
play on the terminal. 
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131 
132 
133 
134 
136 


137 
138 


139 


140 
142 
144 
145 


146 
V47 


148 
150 
151 
153 
154 
156 
157 
158 
159 


160 
161 
162 
163 
165 


SRE RE EHR NR RAR HERERO EEE EER EERE EEE 


* 
* 


HANDLE SHUTDOWN REQUEST BY ISSUING STOP INVITES TO ALL 
OUTSTANDING ENVITE INPUTS PREVIOUSLY 


ISSUED 


* 
x 


RH IO KO I ROR OE A EE EEE EEE EES EEE KEKE EEK 


SHUTDOWN. 


SET TERM-X TO 1. 


STOP-SEARCH. 
IF TERM-NAME(TERM-X) = SPACES GO TO INCR-INDEX. 
MOVE TERM-NAME(TERM-X) TO TERM-NANE-TO. 


MRA EO RR EEE RR EEK EEE EERE EEE E EE EERE EEE EK 


SET UP PARAMETER LIST FOR STOP INVITE INPOT 
HRA TAO EH ER RE AE EK EKA EEE RE EERE EE RE EEE EEE 


* 


MOVE STPINV TO PL-OPC. 
HOVE 8 TO PL~INL. 


* 


SOR ROR FOR SOR IOR BORE OR RO ORO EEE EE OR OR ERE EE EEE EEE EEE ERE KEE 


x 


DO STOP INVITE INPUT OPERATION 


* 


ROR ROR RR ROR NFR FOR IORI OR ERK OR AOR EE FOR BE FORE OOO FE SOR EOE EO EOE KR EEE 


CALL "CCPCTIO USING PARM-LIST, INPUT-OUTPUT-AREA. 


RRR AE RE REE EE RRR ERE REE ERE ERE EEE EERE RES 


* 
* 
* 


IF TERMINAL NOT CANCELLED, THEN ISSUE SHUTDOWN MESSAGE 
IF CANCELLED THEN IF NO INVITES OUTSTANDING GO TO EXIT, 
OTHERWISE GO SET UP FOR NEXT STOP INVITE OPERATION. 


* 
* 
* 


We OR RR ORE EE OR ER RE EEE EEE EEE EEE EE EEE EERE ERE 


IF PL-RTC NOT = 8 GO TO SET-UP. 
IF PL-EFL = 0 GO TO DONE~-BXIT. 
GO TO INCR-INDEX. 


SET-UP. 
AICI IOIGIBI II ICICI OI I IICR IO IOI IDI IOI IO III OR III Ee 


* 


SET UP PARAMETER LIST FOR PUT NO WAIT 


* 


ORR FOR ROR dR FR SOR KK OO OR OR EE EE KEE EE EEE EEE 


MOVE PUTNWT TO PL-OPC, 
MOVE 30 TO PL-OUT. 


TR EK BR EE EEO EK EERE EEE EERE EEE EAE EAE 


* 
* 
* 


INSERT PROPER SHUTDOWN MESSAGE TO TERMINAL REFERENCED IN 
TERMINAL DATA ARRAY. THE MESSAGE IS SET ACCORDING TO 


THE RETUBN CODE 


* 
* 
* 


SRR IOI oR RRR mK tO te 6 OR OO OE OOO 


IF PL-RTC LESS THAN 0 MOVE 'TP ERROR! 


TO MSG-DATA2 
GO TO DISPLAY-OUT. 


IP PL-RTC = 10 MOVE ' NO DATA® TO MSG-DATA2 
GO TO DISPLAY-OOT. 
IF PL-RTC = 0 MOVE DATA-REC TO MSG-DATA2 


GO TO DISPLAY-OUT. 


MOVE ‘BAD DATA* TO MSG~DATA2. 


DISPLAY-O0T, 
MOVE 'CCP SHTDWN LAST REC - * TO MSG-DATA1. 
FOI IOI AU HOO IO II IGOR IO IE KEE EES 


* 


DO PUT NO WAIT OPERATION 


* 


FOI RIOR HOR ROR ROKR oR RIOR IRR dom f OR ROE ki fo dO FO I OO OE 


CALL 'CCPCIO" USING PARM-LIST, INPUT-OUTPOT-AREA. 
INCR-INDEX. 


SET TERM-X UP BY 1. 
IF TERM-X = 5 GO TO DONE-EXIT. 
GO TO STOP-SEARCH. 


Figure 4-14 (Part 4 of 5). Example 2 ~~ COBOL MRT Program 
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Find every terminal name in the save area 
and issue Stop Invite Input to it. If the 
terminal has not been cancelled, a shutdown 
message is issued to it. 


Note: When the last terminal attached to 
an MRT program is processed, issue a Re- 
lease Terminal operation to that terminal 
in order to check the count of outstanding 
Invite Inputs. If the count is greater than 
zero, the program can issue an Accept Input 
operation. For example, suppose an MRT 
program is servicing the maximum number 
of requestors and one or more additional 
requests are queued to the program. If the 
program receives a shutdown-requested 
return code (04) and goes to end of job 
without checking the count of outstanding 
Invite Inputs, the program terminates with 
a 2C termination code (going to end of job 
with outstanding Invite Inputs), and each 
of the queued terminals receives an SO6 
message (program cancelled — shutdown). 


166 
167 
168 
169 


170 
171 
173 
174 


175 


176 
177 
179 


181 
182 


183 
184 


185 
186 


187 
188 
190 
192 


193 
194 


195 
196 


198 
199 
200 
201 
202 
203 


DAO OOO IOI IE IU RII RGIS IG III TO II IGE ab 8 aor 


* PREPARE INPUT OR OUTPUT ERROR MESSAGES HERE AND SET UP * 
* PARAMETER LIST FOR PUT THEN GET TO CONSOL * 
FOI RIO IOI IOI IOI RIO IG IGIDI IOI II CI OI OR iain IG tr 
PUT-GET. 


MOVE PUTGET TO PL-OPC. 
MOVE 29 TO PL-OUT. 
MOVE 2 TO PL-INL. 
FRI OOO ERI IOI IR I TOIGOR IORI IIR AICI ICR III TOR KK 


* INSERT TERMINAL NAME = CONSOL, TERMINAL NAME WHERE ERROR * If an input error occurred, the message 

* OCCURRED, AND INPUT OR OUTPUT ERROR MESSAGE * ‘ i 

SORE IO IG RIOR RRO RRO RIOR OR RR tO ORR REE NET: TP ERROR TNAME BPO EI 1S 
MOVE ' INPUT TP ERROR TNAME =" TO MS-DATA. issued to the console (xxxxxx = terminal on 
IF SWITCH = 6 MOVE ‘OUTPUT! TO MS—DATA1. which the error occurred). If switch equals 

6, a similar output error message is built 








MOVE TERM-NAME-IO TO MS-DATA3. 
MOVE ‘CONSOL' TO TERM-~NAME-IO, 


FAS EIOIIGI IOI IO GIGI OIGOIOIGI EI IO IB ROI IIL IAGO DIORA IA to Rok and issued. 
* pO PUT GET OPERATION TO CONSOL * 
SRR ITO IORI IO ORI IOI RG GOR OR IO IOI RIOR ROI I Hobo Re fOK i tok 3 

CALL "CCPCIO't USING PARM-LIST, INPUT-OUTPUT-AREA. If the system operator keys in TA, the ter- 
2G IOIOI IO IIOIOIOIOR IGOR I RIOR ROR IGIGIGIOIG I IIGOIGUG io oR toi it minal name of the terminal on which the 
* MOVE TERMINAL NAME BACK TO TERMINAL NAME AREA IN TERMINAL * : : . 

a 

* DATA STORAGE ARRAY. CHECK FOR REPLY REQUESTING TO TRY * crop oceutied |s placed insthe termirial 
* AGAIN-~ TA, IF TA NOT PRESENT THEN GO DISCONNECT * name field of the record area and the 
ERAEEAEAREAGE SELES ELERELE CRESTS ERED HEE EESECEE ED CER EEEELESAE SS EE operation is retried. lf the Operator keys 

MOVE TERM-NAME (TERMN-X) TO TERM-NAME-TIO. ; ' 

IF TA NOT = 'TAt GO TO CANCEL-CHK. in any other characters, the terminal 

IF SWITCH = 6 GO TO DISPLAY-ACCUM. name for which the error occurred is 
SRO RORIRRRRORRIOR RRO FOR IGOR FO SIO IO OR RK EE AOE placed in the record area a d if th t 
* IP QUTPUT ERROR MESSAGE THEN GO TRY TO OUTPUT AGAIN * : NO, eENe.cers 
* LF INPUT ERROR MESSAGE THEN GO TRY TO INPUT AGAIN * minal has not been cancelled, a release 


FAI OI IGOR IOI IORI ICI OI IOI IOI IOI ICRA fk 
MOVE 'TRY AGATN TP ERROR’ TO DATA~OUT. 
MOVE 18 TO PL-OUT. 
AERC IIO IOI ODIO IOI DIGIDIOI IOI OIG ISIC IDI IOI EI I I tr 
* SRT UP PUT NO WAIT PARAMETBR LIST * 
SII II IIIS IOI OIIOIOI I IOIDIDIDIIG IORI IG ICR IO OCT IR ok 
PUT-NO-WAIT. 
MOVE PUTNWT TO PL-OPC. 
SOI CII OID IO IOI IIOIIG EI III III IOIO IOI IOI a A 
* DO PUT NO WAIT OPERATION * 
FGI TOR FORO RTO RR III RIO IO ROR eA I ee a 
CALL "CCPCIOt USING PARM-LIST, INPUT-OUTPUT-AREA. 
GO TO INVITE-INPUT. 
JOR IO RIO I OR IIR IOI OR IO BR BOR IOI HEE 
* CHECK TO SEE IF THIS TERMINAL HAS BEEN CANCELLED, IF IT HAS * 


terminal operation is issued to it. 


* AND THERE ARE NO INVITES OUTSTANDING GO TO EXIT, * 
* OTHERWISE GO CLEAR FROM ACTIVE LIST. IF IT HAS NOT BEEN * 
* CANCELLED DO A RELEASE TERMINAL OPERATION, * 


ROR ORR ROR EO ORR KOR RIOR ORR OR RIOR EEE EEE EEE EERE ERE 
CANCEL-CHK. : 

IF PL-RTC NOT = 8 GO TO RELEASE-TERM. 

IF PL-EFL = 0 GO TO DONE-EXIT. 

GO TO CLEAR-ENTRY. 
ROR IO IIR ORI ROR RIOR OR RIOR KE KK EE RAE RARE EAR 
* SET UP PARAMETER LIST FOR RELEASE TERMINA, OPERATION * 
FRI ROO IO RII IOI III OI tO IOI ORR dk aK 
RELEASE-TERM. 

MOVE RELTRN TO PL-OPC. 
SRT IR ORO IOIOR ROR ROR RIOR I fk ROR Ro OR OE 
* DO RELEASE TERMINAL OPERATION * 
SRR ROI IR IOIO IOI IOI ROR boi aR aOR OR OR ORO 

CALL 'CCPCIO' USING PARM-LIST, INPUT-OUTPUT—AREA. 

IF PL-EFL = 0 GO TO DONE-EXIT. 
FRAO IRIS OR HO RR aOR tO RO OR Gg OR a a 


* INITIALIZE THE TERMINAL DATA STORAGE ARRAY ENTRY FOR THE * 
* RELEASED TERMINAL TO BLANKS AND ZERO THE ACCUMULATOR AND * 
* RETURN TO ACCEPT INPOT * 


RE IO III III ICI GRIGIO OIG GISIDI OIG CIOI IIE IOI IOI IO RO ICIOK 
CLEAR~ENTRY. 
MOVE SPACES TO TERM-NAME(TERMN-X).~ 
MOVE ZEROES TO ACCUMULATOR (TERM~X) . 
GO TO ACCEPT-INPUT. 
DONE-EXIT. 
STOP RUN. 








When a terminal is released, reinitialize the 
accumulator to zeros and the terminal name 
save area to blanks. 


Figure 4-14 (Part 5 of 5). Example 2 - COBOL MRT Program 
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To request CCP communication services, you must write 
your FORTRAN programs using the standard application 
program interface, described in Chapter 2. 


‘This standard interface is composed of the following 
elements: 


@ Communications Service Subroutine 
@ Parameter List 
@ Record Area 


Note: This chapter assumes that you are familiar with the 
FORTRAN language. For more information on writing and 
executing FORTRAN programs, see the publication /BM 
System/3 FORTRAN IV Reference Manual, SC28-6874. 


FORTRAN USE OF THE STANDARD INTERFACE 


To use the standard application program interface to the 
CCP, your FORTRAN application program must: 


1. Define the record area and the parameter list (see 
Defining the Record Area and Parameter List). 


2. Set the contents of the parameter list and the record 
area (see Setting the Contents of the Parameter List 
and Record Area). 


3. Call the communications service subroutine, identifying 
the program’s parameter list and record area, to 
initiate the operation (see Calling the Communications 
Service Subroutine). 


4, Examine information returned by the CCP in the 
parameter list and record area and, for input operations, 
process the input data (see Examining Returned 
Information), 


DEFINING THE RECORD AREA AND PARAMETER 
LIST 


Before your FORTRAN program can perform communi- 
cations operations, you must define one or more record 
areas and parameter lists. 
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Record Area 


The number of record areas you must define depends upon 
the logic of your program. You need not always define 
separate record areas for input data and output data, or for 


‘operations with different terminals. 


Each record area defined must be large enough to contain 
the name field and the maximum length of data to be 
received as input in the record area or to be transmitted 

as output from the record area. Define each record area 
you require as an array using an explicit specification 
statement. Define the array as type INTEGER”2. You 
may specify an initial value for the elements of your record 
area array by using the DATA statement. 


Define the data portion of the record area as required by 
your record formats. You should define all data items as 
literal or unpacked data unless data is to be transferred 
over a BSCA line using Text Transparency (see index entry 
terminal attributes), when you can define data fields of 
the record area as binary, packed, or hexadecimal. 


Many FORTRAN application programs require that the same 
record areas be used for records with different formats. By 
defining each record area array needed by the program and 
using EQUIVALENCE statements, you can redefine the 
record area array in a different format. The EQUIVALENCE 
statement specifies that the redefined record area format 
shares the same storage locations as the original record area 
array definition. 


Example: Figure 5-1 shows how to define a record area 
whose record may be in either of two formats. The 
EQUIVALENCE statement assigns the array LTERM to 
the same storage locations used by the first six elements 

of MAREA, ARRAY 1 to the same locations used by the 
next 30 elements of MAREA, and ARRAY2 to the same 
locations used by the last 20 elements of MAREA. The 
DATA statement initializes the six elements of the terminal 
name array, LTERM, to blanks. 
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Figure 5-1. Defining a Record Area Array 


Parameter List 


You must also define one or more parameter lists in your 
program (see index entry parameter list). Define each 
parameter list you require as an eight element array using 
an explicit specification statement. Define the array as 
type INTEGER*2. The first four fields of the parameter 
list should be defined as two-byte numeric elements. You 
can initialize these fields by specifying them ina DATA 
statement. These fields are, in the sequence they must be 
defined in the parameter list: 


1. Return code field. 
2. Operation code and modifiers field. 


3. Field used jointly for output data length, actual 
input data length, count of outstanding Invite Inputs, 
and attributes identifier. 


4. Maximum input/output data length field. 


These fields are the only fields you reference in your appli- 
cation program. The remaining four fields of the parameter 
list are not referenced directly by your FORTRAN program. 
However, they must be defined because space must be 
reserved for them. Your program should never initialize or 
set these fields. 


Unless required by your program, you do not need to define 
separate parameter lists for each operation type nor per- 
manently associate a parameter list with a particular record 
area array. The number of parameter list arrays you define 
in your program need not be the same as the number of 
record area arrays. 
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Example: Figure 5-2 shows how to define a parameter list 
array ina FORTRAN program. The EQUIVALENCE state- 
ment assigns LRTC to the same storage locations as the 

first element of the parameter list array, LOPC to the same 
locations as the second element. LOUTL to the same loca- 
tion as the third element, and LINL to the same location as 
the fourth element. The remaining four elements of 
LSTPRM are the required work area and are not set by the 
FORTRAN program. The operation field, LOPC, is 
initialized to 2 for a PUT operation. The output data length 
field, LOUTL, is initialized to 48. This value might be the 
length of the first output message. The maximum input/ 
output data length field, LINL, is initialized to 60. This 
value might be the total length of the data portion of a 
record area used with this parameter list. 


Return Code Values 

The CCP ignores the contents of the return code field of 
the parameter list at the beginning of a communications 
operation. At the completion of each operation, the CCP 
places a binary value in this field indicating the status of 
the operation, 


This value indicates: 


@ The operation completed normally (value of zero for 
nonchained operations, 14 for chained operations) 


© The operation resulted in an 1/O error (negative value) 


@ The operation resulted in an exceptional condition 


(positive value) 
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Figure 5-2. Defining a Parameter List Array 


The CCP places this value in the return code field of the 
parameter list before returning to your FORTRAN program. 
The FORTRAN program must check the return code value 
upon the completion of each operation. Specific return 
code values and their meanings are given in Appendix F: 
Return Codes. 


Operation Code Values 


For each communications operation, you must set the 
operation code field of a parameter fist to a value which 
indicates the specific operation being requested. You must 
set this value within your FORTRAN program. This field 
can be set by initializing the field in the definition of the 
parameter list array or by moving constants into the oper- 
ation code array element during execution (see Setting 
Fields in the Parameter List \ater in this chapter). 


The CCP does not change this field during the communica- 
tions operation; the contents of the field are the same after 
completion of the operation as they were at the beginning 
of the operation. See Chapter 2: Standard Application 
Interface to the CCP for descriptions of the valid operations, 
Appendix E: Operations Codes summarizes the operations 
and operation code values. 














SETTING THE CONTENTS OF THE PARAMETER LIST 
AND RECORD AREA 


You must set the contents of the following areas before 
performing a communications operation in FORTRAN: 


1. Parameter list array, if different from the last 
operation. 


2. The program name or the symbolic termjnal name 
in the first six elements of the record area array. 
(This step can be omitted if a terminal name is not 
required for the operation, or if the name is the 
same as in the previous operation.) 

3. Output data in the data portion of the record area 
array if the operation is an output operation. 


Setting Fields in the Parameter List 


You reference four parameter fields within your FORTRAN 
program. 


@ Return Code field. 

® Operation Code field. 

® Field used jointly for output length, effective input 
length, count of outstanding Invite Inputs, and attributes 


identifier. 


@ Maximum input/output length field. 
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You need set only the operation code field and the maximum 
input/output length field for input operations. !f you are 
doing an output or an Acquire Terminal operation, you 

must also set the field used as the output length or attri- 
butes identifer. You need never set the return code field; 

it is used only by the CCP to return information about the 
operation to your FORTRAN program. 


Operation Code 


Whenever a communications operation is issued, this 
field must contain a value indicating the operation to be 
performed. You can set this field when you define the 
parameter list array by specifying a DATA statement: 


DATA OPC/2/ 


-You can also set this field by specifying an assignment 
statement. You can assign it either a numeric value or a 
numeric variable. In the following example, the operation 
code element of the parameter list, LOPC, is assigned the 
value 2. 





ISTATEMEN 
NUMBER 


















5-4 





The following example sets the operation code array 
element, LOPC, by moving the numeric variable, PUTOP, 
into it. PUTOP is defined with the value 2. 








STATEMENT] 
NUMBER 

















The CCP never modifies the value in the operation code 
field. You do not need to reset the field if the operation 
to be performed is the same as the last operation using 
this parameter list. 


For more information on the valid operations, see the 
chapter Standard Application Interface to the CCP. 
Appendix D: Operation Codes summarizes the operations 
and operation code values. 


Output Length/Attributes Identifier/Count of Outstanding 
Invite Inputs/Effective Inout Length 


The third field of the parameter list can contain one of 
four different values depending on the type of operation: 


@ Output Length 

® Attributes Identifier 

® Count of Outstanding Invite Inputs 
® Effective Input Length 


The first two values you must set; the third and fourth 
are returned values set by the CCP for certain operations. 


You can set this field when you define the parameter 

list array by means of a DATA statement, or by means of an 
assignment statement, just as you set the operation code 
field. You can assign it either a numeric value or a numeric 
variable. 


Output Length: For output operations, you must place 
into this field the length of the data you wish to write from 
the record area in your program. This length does not in- 
clude the six elements at the beginning of the record area 
array for the name field. This length must be less than or 
equal to the output length specified for the fourth field of 
the parameter list. The output operations you must set a 
data length for are: 


@ Put 


@ Put-No-Wait 


Put-Then-Get 


Chain Task Request 


You must reset this value if the output data length differs 
from the last operation using this parameter list or if the 
field was modified by the CCP. This field is modified by 
the CCP for the following operations: 


@ Get 

@ Put-Then-Get 

® Accept Input 

® Get Terrninal Attributes 
® Acquire Terminal 


@ Release Terminal 


Attributes Identifier: \f your operation code specifies an 
Acquire Terminal operation which sets the attributes of 
the terminal to be acquired, you must place into this field 
a value that identifies the attributes you want to assign to 
the terminal. This numeric value must correspond to the 
number you assigned to the desired set of attributes in an 
Assignment run. 


Effective Input Length: You do not need to set this value. 
For each input operation, the CCP places the actual length of 
the data passed to your FORTRAN program in this field 
before it returns control to your program. 


Count of Outstanding Invite Inputs: On a Release Terminal 
operation and on any input operation that results in a 08 
return code (terminal entered data mode escape and issued 
a /RELEASE command), this field is set by the CCP to 

the number of Invite Input operations still outstanding. If 


this is a multiple requesting terminal (MRT) program, this 
number includes not only the Invite Inputs you have issued 
that have not yet been satisfied by an Accept Input operation, 
but also the number of additional terminals that have re- 
quested your program but are not yet being served by your 
program. 


Maximum Input Length/Output Data Length 


For each operation involving input data, you must enter a 
numeric value into the fourth field of the parameter list 
indicating the maximum amount of input data you expect 
to receive. For each operation involving output data, you 
must enter a numeric value indicating the maximum amount 
of output data you expect to transmit (in this respect, the 
FORTRAN communications interface differs from the 
standard interface defined in Chapter 2). This output length 
must be greater than or equal to the output length specified 
in the third field of the parameter list, but no greater than 
the size of the data portion of the record area with which 
this parameter list is used, or unpredictable results can 
occur. The value does not include the six elements at the 
beginning of the record area array for the terminal name. 
The input operations for which you must place a value in 
this field are: 


e@ Get 

@ Invite Input 
@ Accept Input 
@ Put-Then-Get 


@ Get Terminal Attributes 


© Stop Invite Input (in case input cannot be stopped) 


The output operations for which you must place a value 
in this field are: 


@ Put 
@ Put-Then-Get 


@ Put-No-Wait 
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You can set the value of this field when you define the 
parameter list area by specifying a DATA statement or by 
specifying it in an assignment statement. The CCP never 
modifies the value in this field. Therefore, you do not need 
to reset it unless the maximum input/output length for this 
operation is different from the value set in this field the 

last time this parameter list was used. However, if this 
parameter list is used with more than one record area, you 
may need to alter this value during execution of your 
FORTRAN program. 


Example of Setting Fields in the Parameter List 


Figure 5-3 shows how you can set the operation, output 
data length, and maximum input/output data length fields 
of a parameter fist. The maximum input/output data length 
element is set by initializing it to 125 in a DATA statement. 
It does not need to be reset unless you wish to receive (Get) 


or transmit (Put) data longer than 125. The operation code © 


element and the output length element are set by assigning 
them numeric values. 


Setting the Record Area 


The record area consists of a six-position name field and a 
data area. For an operation with a terminal, except for 
Accept Input and Shutdown Inquiry operations, you must 
place the symbolic name of the terminal to be involved 
with the operation. For Chain Task Request, you must 
place the name of the requested program in the name 
field. You must also provide the data to be transmitted 

in the data elements of the record area array when an 
output operation is to be performed. 


Name Field 


For operations involving a terminal the name you place in 


a record area array must have been assigned to your program. 


You may also identify the requesting terminal by using six 
blank elements as the terminal name if your program is 
not a multiple requesting terminal (MRT) program (see 
index entry). See Chapter 2: Standard Application Pro- 
gram Interface to the CCP for more information on the 
valid terminal namés. 


For a Chain Task Request operation, you must provide the 
name of the program to be loaded in this field. 
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You may set the name field when you define the record 
area array by specifying a DATA statement or by specify- 
ing it in an assignment statement. You need not reset the 
terminal name array elements if the terminal to be used is 
the same that was named the last time the record area array 
was used, unless the name was modified by the CCP. The 
CCP modifies the terminal name field of the record area in 
the following situations: 


@ Upon completion of an Accept Input operation, CCP 
sets the name field to the name of the program or ter- 
minal whose data js placed in the record area array. 


@ Upon completion of any operation using the field name 
array element set to blanks, CCP sets the name element 
to the name of the requesting terminal. 


Output Data Area 


\f the operation to be performed is an output operation, 
you must provide the data to be transmitted in the data 
portion of the record area. You do not need to provide 
data in the record area for operations other than output 
operations because either the data area is not used or data 
is provided to your program by CCP in this area. Data 
provided to your program by the CCP overlays the infor- 
mation previously in the data portion of the data area. For 
example, the input data transmitted to your program by 
the Get part of the Put-Then-Get operation overlays the 
output data transmitted from your program by the Put 
part of the operation. See the Chapter 2: Standard 
Application Program Interface to the CCP for more infor- 
mation on transferring data. 


Note: \f the message to be sent is shorter than the total 
length of the data area, you need not clear the excess area 
to blanks. 


Example of Setting the: Record Area 


Figure 5-4 shows how you can define and set the record area 
when it is used for both input and output operations, Assume 
the CCP has set the terminal name and data area as the 

result of an Accept Input operation. The FORTRAN pro- 
gram then resets the data area for an output operation by 
moving the message ““TRY AGAIN INV DATA” to the data 
portion of the record area array. This message overlays the 
input data transmitted to the record area array by the Accept 
Input operation. Later in the program, the terminal name is 
reset. 
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Figure 5-4. Setting the Record Area 
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CALLING THE COMMUNICATIONS SERVICE 
SUBROUTINE 


Since FORTRAN does not include special statement types 
for terminal !/O operations and other communications 
services, the CCP provides a communications service sub- 
routine, CCPFIO, that converts your FORTRAN program's 
communications requests into a standard request to the 
CCP communication facilities. The functions performed by 
CCPFIO for your FORTRAN program are: 


@ Loads index register 2 with the address of your pro- 
gram’s parameter list. 


@ Places the address of the record area into your pro- 
gram’s parameter list. 


@ Packs the data from A1 format to A2 before it is 
passed to CCP. 


®@ Branches to the CCP. 


@ Unpacks the data from A2 format back to A1 before 
it is passed to the FORTRAN program. 


The CCPFIO subroutine must be linkage edited with your 
FORTRAN application program. See Chapter 9. Program 
Preparation. 


After you have set the required parameter list array element 
and the terminal name in the first six elements of the record 
area array, and have prepared any output data, you are 
ready to request the CCP to perform the operation specified 
in the parameter list array. You make this request by issuing 
a CALL statement, specifying CCPFIO. The names of 

your parameter list array and record area array must be 
passed as arguments to the subroutine. 


The format of the CALL statement is as follows: 


CALL CCPFIO (parameter-list-array-name, recordt-area-array-name) | 











5-8 


In the following example, the name of the parameter list 
array is PARM-LIST; the name of the record area array is 
INPUT-OUTPUT-AREA: 


CALL CCPFIO (PARM-LIST, INPUT-OUTPUT-AREA) 


Control returns to your FORTRAN program at the statement 
immediately following the CALL statement. When the 
return occurs, the following actions have already taken place: 


® For output operations, any output data has been accepted 
by the CCP and, depending upon the output operation 
specified, has been received by the terminal. In any 
case, the record area array is now free for you to use 
again. 


® For input operations, any input data which was to be 
received in the record area array is now in the record 
area array. 


@ For Accept Input operations, the symbolic terminal 
name of the terminal which provided the data in the 
record area array has been set in the first six elements 
of the record area array. 


© For all operations, the return code field in your parameter 
list array has been set indicating the result of the 
operation. 


@ For input operations, the actual input data length has 
been set in your parameter list array. 


© For Release Terminal operations or for input operations 
where the terminal has released itself from the program, 
the count of outstanding Invite Input operations has been 
set in your parameter list. 


®@ For successful Task Chain Request operations, the re- 
quested program is placed on the program request in- 
put queue when control is returned to the requesting 
program. 


EXAMINING RETURNED INFORMATION 


After control has returned to your FORTRAN program 
from the Communications Service Subroutine, you should 
examine returned information supplied by the CCP, 
including one or more of the following: 


@ The return code 


® The symbolic terminal name (if it was set by the CCP) 
or the name of the program that issued the Chain Task 
Request operation. 


@ The count of outstanding Invite Inputs, if a Release 
Terminal operation was performed or if the return code 
value from an input operation indicates the terminal 
released itself. 


@ The actual input data length, if an input operation was 
successfully performed. 


@ The input data, if an input operation was performed 


Return Code 


The CCP always provides a return code after an operation. 
You should never assume that an operation is successful; 
you should always check the return code. In certain cases, 
you will find that no data transfer has occurred. See 
Appendix E for the meanings of specific return codes and 
see Programming Examples, later in this chapter, for 
examples of checking return codes. 


You may wish to perform certain operations in your 
FORTRAN program depending upon the return code value 
set by the CCP. The example in Figure 5-5 assumes that 
you want to branch to one of several locations depending 
upon the value of the return code. The program examines 
the return code value for the following conditions: 


@ The operation was successful and no exceptions occurred. 


@ An EOT was received on a successful operation. 
@ Some other exception condition occurred. 


@ An 1/O error occurred. 


Assume that all array names have been defined earlier in 
this program. Note the use of comments in the example. 


Examining a Returned Name 


On certain operations, the CCP returns the symbolic 
terminal name to your program's record area array. You 
may need to examine this name. 


For example, you may need to examine the name of the 
requesting terminal or the terminal that provided the input 
data to associate new data with data previously received 
by comparing the terminal name in the record area array 
with a saved terminal name. You can do this by specifying 
a DO loop that sets the elements of a six-element save area 
array equal to the terminal named elements of the record 
area array. The save area array must be defined as an area 
of type INTEGER*2. 


If a program can be requested from both a terminal and an- 
other program using the Chain Task Request operation, you 
may want to determine how the program was requested. 
This can be accomplished by checking for a 14 return code, 
indicating a Chain Task Request operation. This informa- 
tion is useful if a program communicates with the requestor 
since your program cannot communicate with a chain task 
requesting program. 


The example in Figure 5-6 saves the terminal name the CCP 
sets in the terminal name elements of the record area array, 
MAREA, by specifying a DO loop. The terminal name 
elements are saved in the array LFEFER. 
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Figure 5-5. Examining Return Code Values 


5-10 


37 


40 41 42 43 44 45 46 47 4B 49 60 57 5: 




















‘ eT CUE al i i 

i 

FAR HERR ER 
CECE Hr ABT OOBENOORBIGEERENGL rH 



































i 7 BS 70 71 72473 74 75 7677 78 79 80! 

















——— 
PROGRAM 





DATE 


FORTRAN Coding Form 


PUNCHING 
INSTRUCTIONS] puNCH 


GX28-7327 
Printed in U.S.A. 


GRAPHIC PAGE OF 
: I ~~TCARD ELECTRO NUMBER* 





IDENTIFICATION 













































































































































































FORTRAN STATEMENT SEQUENCE 
15 1617 18 7 57 68 59 60 61 62,63 64 65 G6 67 68 697071 75.7677 187! 
+ H 
MA, 
ENice | } 4 
ax i | 
2| JLIRIE tr 
EER (| Riis 
LIRE : 4 
+— 
=| (lL . : 
I | 
[| 
[I 
+—+—+- 

























































































































































































Figure 5-6. Saving the Symbolic Terminal Name 


Referencing Saved Information 


In some of your FORTRAN programs, you may need to 
save the information entered on the terminals and reference 
it later in your program. For example, if your program 
receives data from several different terminals, you may need 
to associate new data entered on a terminal with data 
previously entered on the same terminal. To do this, you 
must save the significant data received from every terminal 
you are using and identify that saved data with the name 

of the terminal from which it was received. You can then 
associate new data with the saved data by comparing 

the terminal name set by the CCP in the record area array 
with the saved terminal names. 


You can save information for each terminal in a two- 
dimensional array. Each column of elements in the array 
could refer to a set of elements received previously from 
each terminal. The number of rows and columns specified 
by the array depends upon the number of data items and 
terminals, Upon completion of an Accept Input operation, 
you would then search the array to find the array entry for 
the terminal that just transmitted data to your program. 
You can then associate the new data with the saved data by 
specifying a DO loop. 





40 41 42 43 44 45 46 47 48 41 5 7. 1 67 74 277787! 


Figure 5-7 shows how to set up a two-dimensional array for 
saved information and reference the saved information in 
your FORTRAN program. By searching the array for the 
saved terminal name elements that correspond to the terminal 
name elements in the record area array, you can associate 

the new data with the data that was saved. 


Effective Input Data Length 


!f the Communications Service Subroutine requested an 
operation which transferred data to your program (Get, 
Accept Input, Get Attributes, Put-Then-Get, or Stop 
Invite Input), the CCP also places the effective length of 
the input data into the parameter list array. Because this is 
the length of the data that was actually received by your 
program, you may wish to use this length to control sub- 
scripted operations in your program. For example, you 
may need to scan the input data for a specific character 
or string of characters. To do this you must know the 
length of the input data you must scan. 
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Count of Outstanding Invite Inputs 


On a Release Terminal operation or on an input operation 
where the return code indicates that the terminal released 
itself from your program, the count of outstanding Invite 
Input operations is returned to your program. You may use 
this number to determine whether your program has any 
further terminals to serve or whether it can go to end of 
job. 


Input Data 


If the operation requested by your program is an input 
operation that transfers data, the CCP places the input 

data received by your program in the seventh and succeeding 
elements of your record area array before it returns control 
to your FORTRAN program. The data is then available 

for you to use in your program. 


USING THE SYSTEM OPERATOR CONSOLE 


{f you wish to communicate with the system operator 
through either the 5471 Printer/Keyboard (Models 10 and 
12) or the CRT/Keyboard (Model 15), you must specify 
operations as though the device is a remote terminal. You 
cannot address the system operator console by the TYPER 
subroutine or accept information from the system operator 
- console via the KEYBD subroutine. You also cannot 
address the console or a terminal by using the READ or 
WRITE statements. Instead, you must specify a Put or 
Put-Then-Get operation to CONSOL. CONSOL is the 

only name that can be used for the system operator console. 


Your program can communicate with the system operator 
console at any time. To receive data from the console, 
you must issue a Put-Then-Get operation, which: 

1, Transmits a message to the system operator; and 


2. Accepts a reply from the system operator. 


Control is not returned to your program until the system 
operator has transmitted input data to your program. 


Operations that can be issued to the console are: 
@ Put 
@ Put-Then-Get 


@ Get Attributes 


The console is available at all times to communicate with 

any program or to enter system operator commands. 
However, if the console requests a program, it cannot request 
another program until the first program is initiated by the 
CCP. It is not necessary, nor is it valid, to issue an Acquire 
Terminal operation to the console in order to communicate 
with it. 


Example: The example in Figure 5-8 uses the system 
operator console as the terminal for a Put-Then-Get 
operation. Assume that the parameter list array (LPARM), 
the record area array (MAREA), the console name array 
(CONSOL), and all other symbolic names have been 
previously defined. 


FORTRAN PROGRAMMING CONSIDERATIONS 
When writing your FORTRAN program, remember: 


@ You cannot use either the READ or WRITE statements 
when addressing either the console or teleprocessing 
terminals. 


@® You cannot use the TYPER and KEYBD subroutines to 
address the console. 


@ Use of the GLOBAL and INVOKE statements will lead 
to undefined results due to the storage managing charac- 
teristic of CCP. 


@ (Model 10 and Model 12 CCP) You must not use a 
PAUSE statement. Programs running under the CCP 
are not permitted to issue halts. 


3270 DISPLAY FORMAT FACILITY 


You can use the 3270 Display Format Facility (DFF) 

of the CCP to aid you in formatting and using the 3270 
display. Chapter 8. 3270 Display Format Facility describes 
the programming requirements that are unique to using 3270 
DFF, including the unique 3270 DFF operations, additional 
information that must be placed in the record area for 
certain operations, field types that are unique to the 3270, 
and other information. 


See Chapter 8: 3270 Display Format Facility for an 
example of a FORTRAN IV program that uses the DFF to 
support a single requesting 3270 terminal. 
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Figure 5-8. Using the Console 
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PROGRAMMING EXAMPLES 


Two programming examples are explained in this section: 


@ Example 1 — A FORTRAN program that supports a 
single requesting 3270 terminal without using the Display 
Format Facility. 


@ Example 2— A FORTRAN program that supports 
multiple requesting terminals. 


See Chapter 8: 3270 Display Format Facility for an example 
of a FORTRAN IV program that uses the DFF to support 
a single requesting 3270 terminal. 


Example 1 


Figures 5-9, 5-10, and 5-11 show the flowcharts, messages, 
and listing for a sample hotel reservations inquiry program 
written in FORTRAN. This program transmits two messages 
to a 3270 Model 1 Display System (480 character screen). 
The first message from the program requests the terminal 
operator to enter a room number. The program uses the 
room number as the relative record number to access a 
disk file whose records contain guest and rate informa- 
tion about the room. This information is then formatted 
and displayed as the second message transmitted to the 
3270 terminal. Figure 5-9 also shows how these messages 
appear on the 3270 terminal. 


This program is a single requesting terminal (SRT) pro- 

gram (see index entry) with no program-selected terminals; 
it can receive data from and transmit data to only one 3270 
terminal, However, multiple copies of this program could be 
in main storage at the same time (if your configuration 

of the CCP allows this), each communicating with a 
different 3270 Display System. (If multiple copies are in 
core at the same time, the disk file must be specified as 
sharable during the Assignment stage—see index entry disk 
file sharing.) 


Formatting the Messages for the 3270 Display 


Because this sample program does not use the Display 
Format Facility, this sample program must set all formatting 
control characters for the 3270 display screen into the data 
portion of the record area array and transmit them as part 
of the messages to be displayed (see Figure 5-10). You 

can find the meanings of each of the 3270 screen format 
characters shown in Figure 5-10 in the publication /BM 
3270 Information Display System Component Description, 
GA27-3004. 


The format characters are set by specifying the arrays 

LOC1, LOC2, LOC3, LOC4, LOC5, LOC6, LOC7, and LOC8 
and initializing these arrays to the required 3270 format 
characters (Figure 5-11). The character Z is used to indicate 
hexadecimal characters since some of the format characters 
can only be specified in hexadecimal. The format characters 
are inserted in the data portion of the record area array by 
specifying an EQUIVALENCE statement that sets the 
format character array elements equal to the corresponding 
element in the data portion of the record area array. 


The notes to the right of the listing in Figure 5-11 explain 
the statements used by this program to format the 3270 
display screen. You will also find the comments in the 
listing helpful. 


Notes Concerning this Sample Program 


@ Message mode was defined during the Assignment Stage 
for the 3270 terminal used by this program. (See 
TERMATTR statement in CCP System Reference 
Manual.) This eliminates the need to do repetitive 
input operations unti] EOT is received, 


@ To run this program using a terminal other than the 3270, 
you must remove all coding dependent on the 3270. 
This includes all screen formatting specifications and 
3270 screen control characters within the data. 


@ This program will not accept data with the program 
request. 


® Two different lengths are used for the output length 
field of the parameter list because the two messages 
transmitted by this sample program have different 
lengths. 


® This program specifies a Put operation and a Get 
operation using six blanks as the terminal name. The 
CCP places the name of the 3270 terminal being used 
in the terminal name field of the record area after the 
first Put operation is performed. 
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® To keep this sample program simple, return code checking 


is kept to a minimum. You may want to do more return 
code checking in your application programs. For example, 
when you issue Accept Input you should check for the 
Shutdown Requested return code (04). Also, if data 
mode escape is allowed in the CCP system, programs 
should check for return code 08 (terminal has released 
itself from the program). {t is recommended that each 
installation design its own return code checking and 
console communication routines so that a standard is 
established that is satisfactory to the installation and 
can be used by all application programs. 


This program does not check the length of the input 

data because the terminal operator is requested to 

enter a three-digit room number. If less than three 

digits are entered, the program is canceled. However, you 
may want to check the input data length in your appli- 
cation programs. 
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® Since these are the only two different screen formats 
used by this program, they are both contained within 
the program. For more complete applications, you 
might store the screen formats on disk and read them 
when they are needed by your program. 


@ You could also use the Get Attributes operation in 
this program. If you do not know whether the 3270 
Model 1 or the 3270 Model 2 will request the program, 
you can issue a Get Attributes operation to find out 
which type of terminal requested the program. 


@ If this program were coded and specified as a multiple 
requesting terminal (MRT) program with a MRTMAX-1 
keyword on the PROGRAM assignment statement (see 
CCP System Reference), multiple copies of the program 
would not be allowed in main storage at the same time. 
As the program is written, multiple copies could be in 
main storage at the same time and the disk file must be 
specified as sharable (FILES keyword of PROGRAM 
assignment statement). 


START 


ENTER ROOM # _ 







. Set up parameter list for Put-No-Wait 
to send a message. 

2. Format screen for 3270M1. 

3. Issue Put-No-Wait. (Enter Room # 

message). 





1. Set up parameter list for Get. 
2. Get message (Room #). 








ENTER ROOM #009 







Return Code 
= 0? 








Read disk record. 
record number.) 


(Room # is relative 







ENTER ROOM #009 
ROOM #- 009 
RATE - $18.50 
NAME - JOHN DOE 
ADDR - 114 5TH AVE SW 
ADDR - STURGIS, MINN. 55101 
















. Move disk data: Room # Rate, 
Name, Address. 
2. Format screen for 3270M1. 
3. Set up parameter list for Put, No 
Wait message. 
4. Issue Put-No-Wait. (Room #, Rate, 
Name, Address message). 









( END OF JOB 


Figure 5-9. Communications Flow of Example 1 (FORTRAN SRT Program) 
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First Message 
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SF — Start Field CC  — Command Code 

ATT — Attribute Character WCC — Write Control Character 

IC  — Insert Cursor SBA — Set Buffer Address 

x — Data Character BA — Buffer Address of first character 
EC -—Escape Character position in the field 





Figure 5-10. Message Formats for Example 1 (FORTRAN SRT Program) 
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FURTRAN 


Iv 


// DAD44 UNITNO-8 


*PRUCESS MAP, GODECK 


1 


2 


lo 


ll 


12 


13 


14 
15 


16 
17 


18 
19 


20 
21 


22 
23 


24 
25 


G 


Cc 


PRUGRAM SREURL 


DeFINE FILE 8(10,70yL LAST) 


COR RR IOI CG GIORGI aI ack RIG a dak acc ie ak aia te ake ak ak de ak a ake ac a ake ae ae a 


COMMUNICATIUN AREA 
COCR IG ICICI III OR i iok olga icici aii oii ici aia doit iciiai tick aiictaick ib i aiok i i ag 


c 


G 


C 


c 


a 


INTEGER * 2 PAKM(38) eRECyOPCyOUTL» INL 


INTEGEK * 


INTEGER * 


x 
* 


INTEGER * 


x 


INTEGER * 
INTEGER * 


2 


2 


2 
2 


EWUIVAL ENCE 


1 


EQUIVALENCE 


EQUIVALENCE 


EQUIVALENCE 


LOAREA( 130) > TNAME(6),DATA1L (124) 


TOUT1( 124} »LOCL(6) yROOMX (9) 4L0C203) yRATEX(7) >» 


* 





LOC3(3) yNAMEX(7) ,LUC4(3) sADURX1(7)5 


LOC5 (3) ,ADDRX2(7) 


LUUT2( 26) ,LOC6(6),MESG(12), 





LOC7T(3),1TBLANK(3}),LUCB8(2) 


1D ,RIOM(3) ,RATE(4) pNAME(20) yADDR1L( 20) sADDR2(20) 


IDULRyLPOINT, ENT 


(RTC ePARM( LI) 2 (GPC ,PARM(2)),({GUTL ePARM(3)) 4 


CINL pPARM(4)) 


(TAAME (1) pLGAREA(1))+ (OATAL (1) y TOAREAU7T)) 





(LUCLOL) »TOUTL(1))¢ (RUUMX(1),1LOUTL(7))s 
(LUC2(1) ¢LOUTL(L9)),(RATEX(L), LQUTLI22))5 
(IDOLR»yITOUT1I(29)),(1PUENT,1OUT1L(32)) 
(LOC3(1),1UUT1L(35))_)(NAMEX( 1), 10UTL(38)), 


TQUT1L(68))» 


* (LOC4(1),1QUT1(65)),(ADDRXL(L)» 

* (L005 (1), 10UT1(95)) 5 (ADDRX2(1),10UT1(98)) 
EwUPVALENCE (LOCG(1),1UUT201)),(MESG(1),1QOUT2(7))4 

* (LOCTUL) »LUUT2Z019)), (I BLANK (1) ,TOUT2(22))4 
* (LuC8 (1) +i GUT2(25)) 

DATA LUCL 422740426 140720740721140 724040, ZE840/ 

DATA RUOMX /'R UO M # = Mh 

DATA LUC2] /Z21140,20140425040/ 

DATA KATEX /'R ATE = ‘/ 

DATA LUC3 /21140y2ZC140,2F840/ 

DATA NAMEX /'NA ME = uy 

DATA LUC4 /2114042C240426040/ 

DATA AVDRX1 /tA DOR = ‘/ 

DATA LUCS /21140,40340,20840/ 

DATA ADDRX2 /t'ADOUDR = ‘4 

DATA LOC6 /22740% LF540 520740221140 924040 424040/ 

DATA MESG /*E N TER RUOM #o'/ 


Figure 5-11 (Part 1 of 2). Example 1 -- FORTRAN SRT Program 


Parameter list array 


Record area array 


Output area array 


Message area array 


Disk fields 
Other variables used by the program 


Redefine parameter list array’ 


Redefine record area array 


Redefine output area array 


Redefine message area array 


Initialize 3270 format characters and 
variables 
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26 DATA LUCT 421040, 209409Z21340/ 

2Tt DATA [T3LANK /3*! "/ 
C 

28 DATA LOUC8 /21040,2F040/ 
c 

29 DATA TAME /6*! "7 
c 

30 DATA LDOLR/'S*/,LPOINTS PE. t/,ENT/ EOE 
c 
CRO IR CII GI IO II ARI ROR ROC IOI IR AIO ROR HOR Og i ak ak 
c A PuT SENDING THE MESSAGE "ENTER ROOM #' [TS SENT TO THE 3270 * 
COO I CR COI A IOC CIC I IG CI Oi a ai a a gk ak a ac ara ak ia 
c 

31 OPC = 54 

32 QOUTL = 26 

33 INL = 26 

34 CALL MUVE (TOUT2¢1,26,0ATALyL) 

35 CALL CUPFIU (PARM,1OAREA) 
c 
CRG GIGI ECCI RIGOR ICICI AICO OR NOROR AG RIGA ACR CR RCI aR Aa SR a ae a a a 
C DO A GET FUR THE RUOM NUMBER AND CHECK THE RETURN CODE FOR * 
Cc ZERU. IF IT IS NOT, ZERG GO TO EUJ. * 
C3 RO OO TO II I COI GIO ako ii Ii ior IK OR IC RO IR RGR a Og a a 
c 

36 upc = 1 

37 OuTL = LL 

38 TNL = 11 

39 CALL CUPFIU (PARM,IOQAREA): 

40 TF (RTC.«NE.O) GO TO 20 
c 
COO IOC IORI OIG GIGI i OI Io oii aC doi CII aa aC aK IK dob iO aR qo K&R 
& CHECK IF ENTER AID KEY WAS ON AT GeTy IF IT WAS NOT GO TO EOQJ * 
c CONVERT THE ROUM NUMBER FROM Al FORMAT TO INTEGER FORMAT * 
c THEN CHECK TO INSURE IT IS IN THE RANGE OF FROM O01 TO O10. * 
(Ok RO OO I RO OC GGG it aR ad ING RK ao Ce qo 
c 

41 IF (DATAL(3).NE.ENT) GO TO 20 

42 XRUOM = GET (DATA1L+9y1191.0) 

43 livRGOM = XRUOM 

44 1F (IwROOM.LT.L) GU TO 20 

45 Ir (INKOQOM.GT.10) GO TO 20 
c 
COO OO OK LOI IOI IOI OIG iO oR 2aiaia aiago iii go oi Raga abo 
c READ A RECURD FROM A DERECT-ACCESS DISK FILE.’ THE ROOM NUMBER* 
c REPRESENTS THE KELATIVE POSITION OF THE RECORD IN THE FILE * 
Lo OO oto da 2 OR IORI OR IG I ao af Og Ra HOR 90k 40K 2 ee 
Cc " 

46 READ (8"INROOM?100U00) 10sRUOM,RATE sNAMEyADDR1» ADDR2 
c 
La oo oo do do a IO lai Go OR i AOf OR SRR RI 
c MOVE THE ROUM NUMBER, RATE PER DAY, THE NAME AND ADDRESS OF * 
& THE GUEST iWTO THE GUEST ARRAY: THEN DU A PUT OF IT TO THE * 
Cc 3270 * 
LAO ZOO GIO IOC i ia i ai dak tok dol iii ite it tO 
c 

47 CALL MUVE (RIUMe1,3yL0UT1 +16) 

48 CALL MOVE (RATE*1 2, TUUT1Ly 30) 

493 CALL MOVE (RATEs3+4,1UUT1L 33) 

50 CALL MUVE (NAMce ls 20y,1LUUTL»45) 

51 CALL MUVE (ADDR1e1520,10UT1,75) 

52 CALL MOVE (ADDK2¢1920-10UT1 4105) 

53 CALL MOVE C1OUTL els 1l24,DATALy1L) 

54 IRETRY = U 

55 UPC = 54 

56 OUTL = 124 

57 INL = 124 

5B 10 CALL CUPFIO (PARMyIOAREA) 
c 
CORIO GIOI I O ICI ICO RICE IOI I II IO IOI IR Ri got kek 
Cc AFTER THE PUT CHECK THE RETURN CODE FOR ZERO, IF IT IS NOT * 
c ZERU RETRY THE PUT UNE TIME. * 
Ck a i Oi iO IO GG IG a OIGIOI aig io dak goku i teak ako ik 
c 

59 IF (RTC.EQ.0) GO TU 20 

60 IF (TRETRY.EQ.1) GO TU 20° 

61 TRETRY = IRETRY + 1 

62 GO TO 10 

63 20 STOP 

64 LOOODO FURMAT (Al¢3A124ALy20AL,2U0A1,20A1) 

65 END 


Figure 5-11 (Part 2 of 2). Example 1 — FORTRAN SRT Program 
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Example 2 


Figures 5-12, 5-13, and 5-14 show the flowchart, input/ 
output messages, and listing for a sample FORTRAN multiple 
requesting terminal (MRT) program designed to run under 
the CCP. This program supports up to four MLTA requesting 
terminals. The terminal operator enters a seven-digit 

number preceded by a+, -, or N. The CCP transmits this 
signed number to the FORTRAN program. 


The FORTRAN program: 


®@ Adds the number to the value in the accumulator 
associated with the terminal that transmitted the data 
if the first position is + 


@ Subtracts the number from the accumulator if the first 
position is - 


@ Releases the terminal if the first position is N. 


If a value was either added or subtracted, the new value 
accumulated for the terminal is inserted into the message 
CURRENT VAL = sxxxxxxxxxx ENTER DATA and the 
message is sent to the terminal. 


This sample program also checks for several error conditions 
and transmits the appropriate error message to the terminal 
requesting the operation. 


This sample program is not designed to show the most 
effective way of performing operations. Instead, it shows 

a variety of ways to do things. It uses a variety of opera- 
tion codes that show how data can be associated with a 
terminal by defining a save area array for the terminal names 
and accumulated data. It frequently checks return codes, 
but you can do even more return code checking if you wish. 
Data entered by the terminal operator must be fixed 

length. To allow variable length input fields you could 
include a subroutine in your program to check the effective 
input length returned in the parameter list and align the 
data correctly. This program communicates with the con- 
sole in addition to the requesting terminals. 


The notes to the right of the listing in Figure 5-14 and the 


comments in the listing explain each section of the sample 
program. 
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Set up parameter. 
list for Accept 
Input 

. Accept Input 






C1 


Shutdown Yes 
request 


No 


D1 


Terminal No 
attached 


Yes 


Fi 
Terminal Yes 
cancelled 


o—* 


Gi 
Negative Yes 


return code 


No 


H1 
Positive return Yes 
code (#0) 


No 


Yes 
Operator = N 


No 


Figure 5-12 (Part 1 of 3). Program Logic of Example 2 (FORTRAN MRT Program) 
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C2 






Add terminal to 
attached list 






Terminal 
cancelled 


B1 


F2 


Set cancelled 
switch 


Y 


H2 


1. Set up Put-No-Wait 
(Message) 
2. Issue Put 





. Check input 
length =8 
2. Check valid 
operator 
. Check valid data 

















c5 
om No 1. Set up Put-No- 
Wait (message) 
2. Issue Put 
Yes 
D4 (+) 
Find proper 
accumulator 
Add or subtract 
input to 
accumulator 
F5 











F4 <o | Move *'-" to out- 
put area 
12. Make unit position 
printable 
G4 


1. Set up Put, Wait 
message 


2. Put message 








1. Set up Invite Input 


. Invite input 










a } -{ input TP Error 


3A4 


Retry = try 
again 







C1 
Retry = 


try again 


. Set up Put-No- 
Wait (message) 
. Vssue Put 







: 


--{Release Terminal 









erminal 
cancelled 


© 
“ 


G 


Terminal op. 
2. Refease terminal 


H 
Return 
code = 0 
ry 


. Clear terminal 
name entry in 
attached list 

. Clear accumulator 


1. Set up Release 
1 









End of job 
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Shutdown Routine Console Routine 
Al A4 


R ENTER ENTER 


B1 
. Set up Put-then- 
Get to console. 
2. Issue Put-then- 
Get 












Set index = 1 







CI 








Check entry in 
attached list 






Retry = TA 
(try again) 






Set on release 
terminal indicator 





D4 


RETURN 


Di * 
< Entry blank = @ 


E1 No 





1. Set up Stop 
Invite Input Op. 
2. Stop Invite Input 


F2 


1. Set up Put-No- 
Fi i 

No Wait (message) 
<Terminal cancelled 2. Issue shutdown 
message 


Yes 


" (Hn) 
Yes 


< Effective input 


length =0 
©: 






Add 1 to index 


J1 


Index =5 


K1 


c End of job 
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Input Data Entered by Terminal Operator 


1.2.3.4 56 6{7{8 9 10 11 12[13[14 15 16 17 18 19 & 21 22 23 24 





A fixed length numeric field where S is a+, -, or N and 
X is a numeric digit. All eight positions must be entered, 
except when N is entered in the first position. 












































Data Entered by System Operator on 5471 Printer/Keyboard (Models 10 and 12) or CRT/Keyboard (Model 15) 
(L234 5 6/7 B 9 10 11 12) 13] 14 1g 1617 18 19 20 21 22 23 24 


“tle HH Aah In response to the messages INPUT TP ERROR TNAME- 
Cc fi i ceccec and OUTPUT TP ERROR TNAME-cccccc to the 
: console, the system operator replies TA if he wants to 
Try Again. Any other reply (cc) causes the terminal 


to be released. 






























































1s 
I pc el EI 
: 
| 
a 





Output to the Console 


7203 4 8 6] 7]8 9 10.11 12] 13] 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 92 39-34 353 








These messages are transmitted 
to the console (cccccc = terminal 
name). 






























































Transmitted with value 
in accumulator associated 
with the terminal. 











Issued if data is invalid 








Issued if system operator replies TA 
(Negative return code on Accept Input) 























Issued for negative return code on 
Stop Invite Input 


























Issued for positive return code other 
than 10 on Stop Invite Input 





























Issued for return code of 0 on 
Stop Invite Input 


















































Issued for return code of 10 on 
Stop Invite Input 


Figure 5-13. Input and Output Message Formats for Example 2 (FORTRAN MRT Program) 
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FORTRAN LV 


*PROCESS MAP 


OWOAIKMEWML 


25 
26 


27 


28 


29 


31 


12 
33 


37 
38 


PROGRAM MRPOR1 


INTEGER*2 LPARM(8),MAREA (40) , TERM (44) ,LRTC, LOPC, LINL, LOUTL, LEFL 
INTEGER*2 ACCEPT, PUTNWT, PUTMWT, INVINP, POTGET, RELTRM ,STPINV 
INTEGER*2 CRNTVL(34) ,CONSOL (6), LBLNK,LPLUS, LMINUS,LNNN,N 


INTEGER*2 I,II,J,d3,J3J,MSAV(2) 


INTEGER*2 ERMSG1(2) ,ERMSG2(16), ERNSG3 (12), ERMSG4 (18) ,ERMSGS5 (18) 


INTEGER*2 ERMSG6 (22), ERMSG7 (24) 
INTEGER*4 LZERO 


EQUIVALENCE (LRTC,LPARM(1)), (LOPC,LPARM(2}) , (LOUTL, LPABM (3)), 
1 (LINL, LPARM (4)), (LEFL, LPARM (3) ) 
DATA ACCEPT, PUTNWT, PUTMWT ,INVINP, PUTGET, BELTRM/4,54 ,50,5,3,10/ 


DATA STPINV/1025/7 


DATA LPLUS, LMINUS,LNNN,LBLNK/'+",*-*,*Nt,! 


DATA LZERO/* 00'/ 

DATA CRNTVL/*'C UR RENT VAL= + 
1 ER DATA '/ 

DATA CONSOL/'C ON SOL 'Y 


DATA TERM(1),TERM (12) , TERM (23), TERM (34) /4*' 


DATA LINL/34/ 


DATA ERMSGI/'T A f/ 

DATA ERMSG2/* T P ERROR TNA M 
DATA ERMSG3/'I N PUT ouTPUT '/ 
DATA ERMSG4/'T R Y AGAIN TP E 
DATA ERMSGS/'T R Y AGAIN Inv 
DATA ERMSG6/'C C P SHTODWYNH LAS 
DATA ERMSG7/'T P ER RORBAD DA 


CRO IOIIIOIO IIR IOI ORI ROR TOI SOR ER IR EO EE ERE TEE REE EEK 
C ILI=INDEX POR TERMINAL ARRAY, JJ=SWITCH, JJ=1 INPUT, 


ta 


HAOD 


‘/ 


R 
A 


A 


‘s 


'/ 


OR '/ 
TAS 
REC 

yO 


C <JdJ=ADDITIONAL INDEX FOR VARIOUS SHORT TERM PURPOSES. 


Cc 
c SET UP PARAMETER LIST FOR ACCEPT INPOT 


CERRO RE EEE EK EK EEE RE EERE REE REE EERE ER EE REE EERE EEE EEE EE EE EEE 


00100 Jug=1 
LOPC=ACCEPT 


CRA RO EE EEE EE EEE ERA EEE EEK EEK EERE RE EE ER ER EEEEREE 


c DO ACCEPT INPOT OPERATION 


RA HK EE EEE ERE EE EE EEE CREEK EEE ER KRER EEE EE EE EEE EEE 


CALL CCPPIO (LPARM, MAREA) 


CREE EE EKER EERE EE EK ERE EER ERE KE ERE EE EEK EE EERE EERE EERE EERE EE EKEKEREEEREEE 


c CHECK TO SEE IP A SHOTDOWN HAS BEEN REQUESTED 
CORIIIAIO I IIIIOI IO RIO III RIO II ik REI IOI HO Et IE 8 OR EE EOE 


IF (LRTC-4) 00190,02500,00190 


CER EER EERE REE EEE ER EEE EEE EEE EE EER EER EEE EEE EE EEE EEE EERE EE REE EKER EEE 


c DETERMINE IP TERMINAL IS ALREADY ATTACHED, NCOMP IS SET TO 0 IF 
c FIRST 6 ELEMENTS IN MESSAGE AREA MATCH A 6 ELEMENT TERAIWAL 


c NAME IN THE TERMTWAL DATA STORAGE ARRAY 


CREE EERE KEE EEE EERE KERE EERE EERE KE EERE EERE EERE EKEEEEEEKEEEREEER EEE EEE 


00190 DO 00200 IT=1,34,11 


IP (NCOMP(MAREA,1,6,TEBN,IT)) 00200,00600,00200 


00200 CONTINUE 


CI IOI ROI IO IIR ICI CIOS II NOE EO RO 


= vs 


DATA 


JJ=7 OUTPUT. 


Cc CHECK TO SEE IF TERMINAL HAS BEEN CANCELLED.IF IT HAS BETUBN 
Cc TO ACCEPT INPUT IF INVITES ARE OUTSTANDING, 


Cc OUTSTANDING GO TO EXIT. 


CHR RRR ERE ER EEE EKER ES EKER ERA ES EEE EEE ERE EERE EAE ERE EES CREE REESE EEEES EE 


IF (LRTC-8) 00250,00220,00250 
00220 IF (LEFL) 00100,09000,00100 


CR HR ROR RO ROR RIOR RR RIOR EEK ORE 


'/ 





IF NO INVITES ARE 


Cc LOCATE A BLANK 6 ELEMENT TERMINAL NAME SPACE IN THE TERMINAL DATA 


Cc STORAGE ARRAY 
Cc NOTE: 


NO MORE THAN 4 TERMINALS WILL BE ALLOWED TO COMMUNICATE 


¢ WITH THIS PROGRAM IP ASSIGNMENT SPECIFI€S 4 TERMINALS 


CR RR RK EE REE REE EE EEE EERE EEE EERE EEE EER ERE 


00250 DO 00300 IT=1,34,11 
IP (TERM({II).EQ.LBLNK) .GO TO 00400 
00300 CONTINUE 


CR RR EO OR RR ERE ERR ERE EE ERE RE EERE EERE 


c INSERT THE NEW TERMINAL NANE INTO THE SPACE JUST LOCATED AND ZERO 
c THE ACCUMULATOR ASSOCTATED WITH THIS LOCATION 


CO HO RR EE EO EO EEE RE REE REAR KE KEKE KEER ERE 


00400 CALL MOVE (MAREA,1,6,TERM,II) 
CALL FILL (TERM,II+6,IT+10,LZER0) 
GO TO 00610 


CAE ORR RII ROI II OO EO RR Hee $8 tok oto aio tok 


Cc CHECK TO SEE IF TERMINAL HAS BEEN CANCELLED. 


c TERMINAL NAME AREA AVAILABLE FOR NEW ENTRY 
CRI OI ISI I RIO RFI RII TOR OR ORE CE EK 


IF IT HAS GO MAKE 


Figure 5-14 (Part 1 of 4). Example 2 — FORTRAN MRT Program 
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or eee 


Define parameter list array, record area 
array, Save area array, console name array, 
output message array, error messages, and 
other variables used by program. 


Set parameter list fields equal to elements 
in parameter list arrays. 


Initialize operation code fields, output 
messages, Save area array, error messages, 
and other variables used in program. 


Set operation code field equal to numeric 
variable for Accept Input. 


Determine if the terminal name for the 
terminal that transmitted the input data is 
in the save area array. If it is, the data is 
added to the accumulator associated with 
that terminal. If it is not in the save area 
array and the terminal is not cancelled, 

the terminal is added to the save area array. 


40 


41 
42 
43 
44 
45 


46 
47 
48 


49 
51 


55 
56 
57 


58 
59 


60 
61 


63 
64 


65 
66 


67 


68 
69 
710 


71 


72 
73 


74 
75 


00600 IF (LRTC-8) 00610,04900,00610 
COI III IORI IOIOI IO ITO IOI IOIOIDIDIDIGI IEG IOIDIGE III IE AR SE ® 
C CHECK FOR INPUT ERROR INDICATIONS, ISSUE ERROR MESSAGE IF RETURN * 
c CODE NOT EQUAL TO 0, OR IF LENGTH NOT 8B * 
C CHECK FOR VALID OPERATOR, IF OPERATOR EQUAL TO N GO RELEASE TERMINAL 
CORA OIG III III III IOI IOI IOI IIOR IO IRE AIRE 
00610 IF (LRTC) 02800,00650,00700 
00650 IF (MAREA(7).EQ.LNNN) GO TO 04800 

IF (LEFL-8) 00700, 00660 ,00700 
00660 IF (MARBA(7).EQ.LPLUS) GO TO 00900 

IF (MAREA(7).EQ.LMINUS) GO TO 00900 
COICO OIG IGE III IOIDIDIGOIIOIOIIDIOISI IBIS III IGOR I ICI SIR 
C ASSUME BAD OPERATOR, ISSUE INVALID DATA MESSAGE * 
CO III IOI IIR IOI IO OIRO TORII RR OR AAR EEE EE EEE EET TEE 
00700 CALL MOVE(ERMSG5,1,18,MAREA,7) 

LOUTL=18 

GO TO 04300 
COR IR IOIOISIIIOIIOIOII III IOIDIDIG IIS IO AGI UIO OIE RII IOE I AIA I IEE 
C CONVERT THE VALUE RECEIVED AS INPUT FROM CHARACTER (A1) TO ZONED * 
c DECIMAL (D1) PORMAT * 
c IF N NOT EQUAL TO 0 SET UP INVALID DATA MESSAGE * 
CII III IGIOI OI IORI IDIIGR RGIS BOR IGRI AIOE TRIE A RR TOI ER EE HD 
00900 N=O0 

CALL AIDEC(MARBA, 8, 14,N) 

IF {N) 00700,01000,00700 
CRIS IOII IOI IGG IO IOI ISIE III OIC Fa IORI ICES EE EEE EEE 
C NOW ADD THE VALUE RECEIVED AS INPUT TO THE VALUE IN THE * 
c ACCUMULATOR ASSIGNED WITH THE TERMINAL NAME * 
COO IOI III IGIIGISIC IODIDE IOI GIO IIS IEICE IO IOC I IO IO I ae 
01000 Jdd=II+6 

N=0 

IF (SAREA(7).EQ.LMINUS) GO TO 01500 
CO IOI IGICIOIG OID GIGI OGIO RIOR IG II IOIO I UII IE 


c ADD VALUE RECEIVED TO VALUE IN ACCUMULATOR * 
CREO IOI ISI III TOR FOIE IOI AIO IOI EE te 

CALL ADD (MAREA. 11,14, TERM, JJJ,JJJ+4,N) 

GO TO 01600 
01500 CALL SUB(MAREA, 11,14, TERM, JJJ,JJJ+4,N) 
CORIO FOR FOR RIOR IERIE OR AOR IRCCS IR NOR RB IE RE 
c SET UP TO DISPLAY RESULTS IN ACCUMULATOR, TO TERMINAL * 
c NOTE: IF OVERFLOW GCCURRED MAX VALUE WILL BE DISPLAYED; ALL 9°S * 
CORIO IO AOI GOO IRR TOR FOR OIG IO III ICICI III ICIOIO 2 IR IO IO IE AOE 
01600 CALL MOVE(CRNTVL,1,34,MAREA,7) 

CALL MOVE(TERM, JJJ,J0J+4,MAREA, 25) 
(CIO IOI III III IOI III II RAO III FIORE SE SOE ATOR BRACE ER, 
c SET INDICATOR N ACCORDING TO THE SIGN OF THE ACCUMULATOR VALUE THEN* 
C SET LAST DIGIT OF ACCUMULATOR VALUE POSITIVE * 
(CARRIO IDIOIII IGG IOIBISIIOIIUIGEIIDIOIIOIEBIOIIOIGOIGIDEI IDOE IDIG IGE IEE IG ak 

CALI NSIGN(MAREA, 29,1,N) 

IF (N) 01800,01900, 01900 
071800 MAREA(19)=LMSINUS 
CR II IGIIOIOISI I IOIIOIOIIIDIOIIIGOIOIEICIOIOIICIIOICEIGIOIDIOIOI I OIOIO IDI I IO SOI IE IG 
c CONVERT THE ZONED RESULTS TO CHARACTERS IN A1 FORMAT FOR OUTPUT * 
CARR IIS III IOIIUIOI IOI IO ICICI IOI IOI IEICE IIR IO IO ICR tk 
01900 N=0 

CALL DECA1(MAREA,20,29,N) 
CORIO CIO IO IO IIIS IO ICIG OIC III IOIOIOII IOI ICICI IO IO A I 
c SET UP PARM LIST FOR PUT MESSAGE WAIT * 
CRI IOI III II ISIDIG I IGOR IOIIRIOIGIDIDIOI III III ISI CIO Ea Ie 


LOPC=PUTMWT 


LOUTL=34 
CIO IO I IOI II IOI OIOIIOIOIDIO I IGIGIGIGIO II IOIOIUI IG ICIOIOIG IOI ICICI IOI DE 308 
c DO PUT MESSAGE WAIT OPERATION a 


CORR IOI RIOR RIO ROR IRR ROR OR RIOR SORE AOR RIOR EE RTA HEE EEE EERE ERE EERE 


CALI, CCPFIO (LPARM, MAREA) 
CFR RII R OR RIOR ORB ROCIO FOTO EAR TOO IRR TOTO OR OR TORI TEE 
c CHECK RETURN CODE TO SEE IF OPERATION WAS SUCCESSFUL * 
c IF RETURN CODE NOT EQUAL TO ZERO GO ISSUE ERROR MESSAGE * 
CIRO TO FOI CIO ITO IORI SR SORT SOR IB SORIA I IR ER RTO EE EEE EE 
IF (LRTC) 02100,02200,02100 
02100 JJ=7 
GO TO 02800 
COICO IIDC ROR RIOR ROR NOIR ITO AE SR REE CER EEE REE EEE REESE EE 


Cc SET UP PARAMETER LIST FOR INVITE INPUT * 
CIAO UII III III IOI IIR IO IORI IORI ROR BORE IR EEE RHEE EEE ERE 


02200 LOPC=INVINP 
CA ERO OI III ISO OR RAR ORR EEE EEE EERE EEE ERE EERE ORES OE RERES 
Cc DO INVITE INPUT OPERATION : * 
CCI TOI IOI AIR ITO IOI IOR IIIT IE OEE RI EEE EEE BERET EEE 

CALL CCPFIO (LPARN, MAREA) 

GO To 00100 
CRI III OCI IORI ROR ROR ROR ROI SI OE ERE EO EE EE EEE ORES EEE 
c HANDLE SHUTDOWN REQUEST BY ISSUING STOP INVITES TO ALL OUTSTANDING * 
c INVITE INPUTS PREVIOUSLY ISSUED * 
CORIO OIG RII IOI ICRC ORCI ICICI NOOR AOE Bi A 1 IO AO Ee EE 
02500 DO 02600 T1=1,34,11 

IF (TERM(II)~EQsLBLNK) GO TO 02600 

CR RIOR ROR ROI OIRO BRACE BR RR OE EO EE REE EE 


c SET UP PARAMETER LIST FOR STOP INVITE INPOT * 
CIO IOI III IOI ICICI III I IO IR SOI EOI SO RII IIE HE EE 


Figure 5-14 (Part 2 of 4), Example 2 — FORTRAN MRT Program 


If the first position of the input field is +, 
the data is added to the accumulator ele- 
ment associated with the terminal that 
transmitted the data. If the first position 
is -, the data is subtracted from the termi- 
nal. If the first position is N, the terminal 
is checked to see if it is cancelled. 


lf the first position of the input data is not 
+,-, or N, a message is issued to the terminal. 


Insert accumulated value associated with 
the terminal into the output message and 
display it on the terminal. 


Note: When the last terminal attached to 
an MRT program is processed, issue a Re- 
lease Terminal operation to that terminal in 
order to check the count of outstanding 
Invite Inputs. Uf the count is greater than 
zero, the program can issue an Accept Input 
operation. For example, suppose an MRT 
program is servicing the maximum number 
of requestors and one or more additional 
requests are queued to the program. If 

the program receives a shutdown-requested 
return code (04) and goes to end of job 
without checking the count of outstanding 
Invite inputs, the program terminates with 
a 2C termination code (going to end of job 
with outstanding Invite Inputs), and each 
of the queued terminals receives an SO6 
message (program cancelled -- shutdown). 
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76 


78 


79 
80 


81 


97 
98 


99 
100 
101 
102 


LOPC=STPINY : 
CALL MOVE (TERN, IL,II+5, MARER, 1) 
CEU EKER AKER KE AEKE EERE KERR ERE EEE AERA EAE AEE EERE KEE KEES ERE ERE 
C DO STOP INVITE INPUT OPERATION * 
CO I RO ROR OK RI BORER ORK ERK RIOR KER EE EEE EERE EKER KEK 
CALL CCPFIO (LPARM, MAREA) 
CORR ORR ROO tO OE RE EO EEK KEK EEE REE EEE 
C LIF TERMINAL NOT CANCELLED, THEN ISSUE SHUTDOWN MESSAGE. IF TERMINAL* 
c CANCELLED THEN GO TO EXIT IF NO OUTSTANDING INVITES, ELSE GO * 
c SEARCH FOR NEXT ACTIVE TERMINAL. * 
CRO RR ER RR RE FOR OR BR BOR EK RE KE RK RE RR ROR EE EE KEE EEE 
IF (LRTC-8) 02510,02508,02510 
02508 IF (LEFL) 02600,09000,02600 
CR ROI ROR OR ROR KK RRR RK KEE KER ERE REE EE EER ERE EERE REE 


C SET UP PARAMETER LIST FOR PUT NO WAIT * 
CRP REE EK ERR RE ERR RE ERR EEK EK KE REE REE ERK KK EEE EKER EKER EEK EERE EEK 
02510 LOPC=PUINWT 

LOUTL=30 


CORR RIOR IIR RIOR IOI IOI IIIA I RII IOI III III IOI RIE 
c INSERT PROPER SHUTDOWN MESSAGE TO TERMINAL REFERENCED IN TERMINAL * 
Cc DATA ARRAY. THE MESSAGE IS SET ACCORDING TO THE RETURN CODE * 
CRI TO TORR AOI RRO BOR AIO IO RRO RB BEE ROR MOTE EERE EE 


IF (LRTC) 02520,02535,02525 


02520 JJI=1 
GO TO 02528 
02525 IF (LRTC-10) 02526,02527,02526 
02526 JIJ=9 
GO TO 02528 
02527 JIJ=17 
02528 CALL MOVE(ERMSG7,JJJ,JJS+7, MAREA, 29) 
GO TO 02558 


02535 CALL MOVE (MAREA,7,14,MAREA, 29) 

02558 CALL MOVE (ERMSG6, 1,22, MAREA,7) 

CRP R EKER EK ERK REE EEE RR EERE RE EERE ORK EEE EERE EERE EEK ERE 

C DO PUT NO WAIT OPERATION : * 

CRE ERE RE EE EE EEE KK REE ER RE RRR KOR KEE KR ERR RRR EER KKK ERE KEE ERE KERR EE 
CALL CCPFIO (LPARM, MAREA) 

02600 CONTTNUE 


GO TO 09000 
RA OR IOI IO FOR RIO IOI ROR OR SSO ORR SO ROR EE RIOR EEE 
c PREPARE INPUT OR OUTPUT ERROR MESSAGES HERE * 
c SET UP PARAMETER LIST FOR PUT THEN GET {TO CONSOL * 


CRRA RH HK E ERR KER KEE ERK RE KK EKER EE ERA REE EERE HEE ERE KEES ERE ERE 
02800 LOPC=PUTGET 

LOUTL=28 
CR OR EE KEKE KEK EEK ERE EEE EE REE ERK EEE ERE RE EE ESE EERE EE 
C INSERT TERMINAL NAME=CONSOL, TERMINAL NAME WHERE ERROR OCCURRED, * 
c AND INPUT OR OUTPUT ERROR MESSAGE * 
CRM RRR EER RRR KR EERE REE EERE REE KEE HOEK EKER RK RRR RE RE EE ERK 

CALL MOVE (CONSOL, 1,6,MAREA, 1) 

CALL MOVE (ERMSG3,J3,JJ+5, MAREA, 7) 

CALL MOVE{TERM,IIT,I1+5,MAREA, 29) 

CALL MOVE (ERMSG2, 1, 16,MAREA, 13) 
CREE ERE EE EERE ERE REE ERE RR EER REE ERK RE EEK REE KEE EER EER EEE EKER ERE EERE EEE 


c DO PUT GET OPERATION TO CONSOLE * 
CORR OR RIOR IOI ROI IR AOR BOI IO EFI SR OI IO IOI IRIE SII EE 
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lf an input error occurred, the message 
‘INPUT TP ERROR TNAME xxxxxx'’ is 
issued to the console (xxxxxx = terminal 
on which the error occurred). If an output 
error occurred, a similar output error 
message is built and issued. 


103 CALL CCPFIO (LPARM, MAREA) 
CORIO IOI OREO IOIOR III RIO TOO III I IOIO IO IOI IOI I EIR IO 
C MOVE TERMINAL NAME BACK TO TERMINAL NAME AREA IN TERMINAL DATA * 
Cc ARRAY * 
C CHECK FOR REPLY REQUESTING TO TRY AGAIW--TA * 




















Cc IP TA NOT PRESENT THEN GO DISCONNECT * 
CR ARR HER IO IIR RE ROR OR EEE EE BEER EE 
104 NSAV (1) =NAREA (7) 
105 MSAV (2) =MARBA (8) 
106 CALL NOVE(TERN,IT,II+5,MAREA, 1) 
107 IF (NCOMP(MSAV, 1,2,ER8SG1,1)} 04800,03800,04800 
CIRCE HORE EE EE EE OE EE EEE EE EEE ER ERE EEE E EEE EEE EEE 
C IF OUTPUT ERROR MESSAGE THEN GO TRY TO OUTPUT AGAIN * 


CA RR RR RRO I EE EE EIT EOE REE EEE EE EEE EEE EEE 
108 03800 IF(JJ-7) 03810,01600,03810 
COO IOI ISI IORI IOI RIOR IOIDIDII IIIS ROR RIO III I IO 
c IF INPUT EBROR MBSSAGE THEN GO TRY TO INPUT AGAIN * 
CORREO RE ROR IIIA HOR AOE BRON BOI ACEO IO EE EEE EE 
109 03870 CALL MOVE(ERMSG4,1,18,MAREA,7) 


lf the system operator keys in TA, the 
terminal name of the terminal on which the 


110 LOUTL=18 error occurred is placed in the terminal 

CO IOI IO IO RII II FOR IIR SOR AOR ROO 1 BEE HOR ‘i 

name f h = 

© SET UP POT WO WAIT PARAMETER LIST = a ield of the record area and the opera 

(CH A A ACH A RA RR ERR I EE EE ER tion is retried. If he keys in any other char- 
111 04300 LOPC=PUTNWT acters, the terminal name for which the 

Re 0 RO OO NIC AI RI OER A OE OE RE cc planes iaah d 

¢C DO PUT NO WAIT OPERATION i error occurred is placed in the record area 

CR BRR RR ROR RRR NOR BOR RO RE RRR RO SOE EE EE EE OR EE EEE and, if the terminal has not been cancelled, 
112 CALL CCPFIO (LPARM,MAREA) a Relea inal operation is issued to i 
AAG Gio mo 023200 se Terminal operat issued to it. 

COIR OIE OIE IO IO IOI IOI IOI IE OIE IGISIO IE IGE IOI OIOIOI IOI IOI IOI I I IIR IO te 

Cc CHECK TO SEE IF THIS TERMINAL HAS BEEN CANCELLED. IF ITT HAS GO * 

c REMOVE IT FROM THE ACTIVE LIST. IF NOT CANCELLED DO A RELEASE * 

c TERMINAL OPERATION. * 


CIROIE OR IO RO IO II REI IO IOI RR Bok RAO OR IO IIR I BR SO RK 
Vu 04800 IF (LRTC-8) 04850,04900,04850 
COICO IOI OO IE IER IOIIOIOIIOIDIDIBIOI IOI ICI IIOIOIGIOIOIDI IO IOIOIOIO SOI I AR IR 
c SET UP PARAMETER LIST POR RELEASE TERMINAL OPERATION * 
COI EIEIO OI IO IOI IOIO I IOI III IO IIIB ICI ICICI IIR I I EIA IE SO EAE 1H 
115 04850 LOPC=RELTRM 
CR RR RRR IR HO ICR RO ROR AOR RK EE EE EE EE RARE ER EE EE EEE 
c DO RELEASE TERMINAL OPERATION * 
COR IRR OR IO SOR BOR FOR ROI IRF SOR ICR ROR REE REE OEE BEER EEE 
116 CALL CCPFIO (LPARN,MAREA) 
CREO IOIGI IGOR IO IO I IOIOIIGIOI IIE IGIOISIOI IOI IG OIE EI IOI IO ICICI AIOE JOR 18 # i 
c SET THE FIRST ELEMENT OF THE TERMINAL NAME AREA OF THE ARRAY TOA * 


c BLANK, SIGNIFYING THAT THIS ENTRY AND ITS ACCUMULATOR ARE * 
c AVAILABLE. RETURN TO ACCEPT INPUT IF MORE INVITES ARE OUTSTAND- * 
c ING OTHERWISE EXIT. * 
CHIH NA I HR HE EEE OE ER OR RE RR BEE EEE EE EEE IE 

1417 04900 TERM (II) =LBLNK 

118 IF {LEFL) 00100,09000,00100 

119 09000 sTOP 

120 END 


Figure 5-14 (Part 4 of 4). Example 2 — FORTRAN MRT Program 
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Programs written in RPG II can communicate with terminal 
devices via the CCP by means of either or both of the 
following two RPG II facilities: 


@ SPECIAL files -One or more SPECIAL files can be 
defined for communications devices; different file 
types can be assigned, depending on how the device 
is usec. 


@ EXIT/RLABL operations - Terminal operations can be 
requested using EXIT and RLABL operations with sub- 
routines provided by the CCP. 


You can issue all of the communications operations 
described under Operations in Chapter 2 through either 
the SPECIAL or the EXIT/RLABL interface, In general, 
however, use of SPECIAL files is recommended for opera- 
tions involving data transfer, such as Get, Put, Accept 
Input, Put-Then-Get, and Stop Invite Input (which may 
result in a Get), EXIT/RLABL is best suited for use in 
non-I/O operations, such as- Acquire Terminal, Release 
Terminal, and. Shutdown Inquiry. By following this 
general rule, you can eliminate the need for RPG II logic 
to move fields from a record area when no data has been 
received. 


Programming for non-TP devices (console, card devices, 
printer, and disk) under the CCP is the same as in RPG II 
programs that are not written to run under the CCP, with a 
few exceptions: 


@ The system operator console is treated as a terminal 
device under the CCP. Therefore, you must communi- 
cate with the console through.either SPECIAL or 
EXIT/RLABL; you cannot use the name CONSOLE 
(Model 10 Disk System and Model 12) or CRT77 
(Mode! 15) on File Description Specifications. 


@ You should not specify a core index for disk files 
{columns 60-65 of the File Description Specification). 
The CCP builds a core index based on the MSTRINDX 
keyword of the DISKFILE assignment statement (see 
CCP System Reference Manual). \f you also specify a 
core index in your program, you will cause unnecessary 
code to be generated for your program. 


Chapter 6: RPG II 


@ You should be aware of how other programs running 
under the CCP are using disk files that you use in 
your program, especially if records are being added to 
the files. See index entry disk file considerations for 
detailed information. 


@ You cannot use magnetic tape files in programs written 
to run under the CCP, 


Note: You are assumed to be familiar with the RPG II 
abject program cycle and the RPG I| language, including 
SPECIAL files, arrays, and EXIT/RLABL, READ, and 
EXCPT operations. If you are not familiar with these 
RPG II facilities and operations, you should consult the 
following publications: 


@ /BM System/3 RPG I Reference Manual, 
$C21-7504 


@ /BM System/3 RPG I! Additional Topics Programmer’s 
Guide, GC21-7567 


© /BM System/3 RPG II Disk File Processing Programmer’s 
Guide, GC21-7566 


RPG II Use of the Standard CCP Interface 


The interface used by RPG I! application programs for 
CCP communications operations differs somewhat from 
the standard interface described in Chapter 2. However, 
you should read Chapter 2 before reading this chapter, 
since most of the information in that chapter also applies 
to RPG II. The differences in the RPG II interface are 
due mainly to the fixed nature of RPG II object program 
cycle, a characteristic that COBOL, FORTRAN, and 
Basic Assembler do not possess. The basic elements of 
the interface, although somewhat different in content 
and use, remain the same: 


@ Parameter list 
@ Record area 


@ Communications service subroutine 
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COMMUNICATIONS INTERFACE USING RPG II 
SPECIAL FILES 


One method of performing operations with terminals under 
the CCP is to define one or more SPECIAL files for terminals 
in the File Description Specifications. SPECIAL files can 
be defined in a variety of ways, depending on the needs of 
the particular application. For example, a program that 
performs both input and output operations with a single 
terminal might define one SPECIAL file as a primary input 
file, to be used for input operations with the terminal, and 
a second SPECIAL file as a detail output file, for output 
operations to the terminal. Thus, two SPECIAL files would 
be defined for a single terminal. 


Suppose, on the other hand, the program communicates 
with several terminals. The same two SPECIAL files defined 
for communication with a single terminal could be used for 
communication with several terminals - one for all terminal 
input and one for all terminal output. 


It is also possible to define a single SPECIAL file for both 
input and output operations with one or more terminals. 

For example, a SPECIAL file could be defined as a Combined 
Demand Input and Exception Output file to be processed by 
READ and EXCPT operations in Calculations. 


These are just a few examples of the variety of ways of 
defining SPECIAL files for use in terminal operations via 
the CCP. Any of the following file types can be defined as 
a SPECIAL file to be used for 1/O operations with one or 
more terminals: 

@ Primary Input file 

@ Secondary Input file 

@ Demand Input file (used with the READ operation) 


e@ Exception, Detail, or Total Output file 


@® Combined Demand Input and Exception Output file 
(used with READ and EXCPT) 


® Combined Primary or Secondary Input file and 
Exception Output file 


@ Combined Frimary or Secondary Input and Detail 
Output file 
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Parameter Array for SPECIAL 


In the RPG I] communications interface to the CCP, using 
SPECIAL, each parameter list must be contained in an 
RPG II array consisting of five elements — six positions 
each. The contents of the parameter array for SPECIAL 
are shown in Figure 6-1. Notice that the contents of the 
parameter array are similar to the contents of the standard 
parameter list defined in Chapter 2, except that no CCP 
work area is provided and, for SPECIAL input operations, 
the symbolic terminal name with which the operation is to 
be performed is placed in the parameter list. 


Unlike the standard interface defined in Chapter 2, certain 
parameters for the SPECIAL interface are placed in the 
record area, instead of parameter array. See Performing 
CCP Operations with SPECIAL, \ater in this chapter, for 
details of using the parameter array and record area in 
various operations. 


The parameters for an operation can be placed in the para- 
meter array during RPG II compilation, at pre-execution 
time, or during execution of the program, depending on how 
the array is defined in Extension Specifications (see Defining 
the Parameter Array, later in this chapter). 


Record Area for SPECIAL 


When using RPG II SPECIAL, input and output record areas 
for CCP operations are defined by coding Input Specifica- 
tions and/or Output-Format Specifications, As shown in 
Figure 6-2, the formats of the input and output record areas 
for SPECIAL are different from the standard record area 
format defined in Chapter 2. An additional eight positions, 
besides the name field, must be set aside in both input and 
output record areas; therefore, data always begins in posi- 
tion 15. Figures 6-3 and 6-4 show example RPG II specifi- 
cations for input and output record areas. 


Input Record Area 


On input operations, the CCP places the following informa- 
tion in the record area, as well as in the parameter array: 


@ Return code for the input operation and the last output 
operation 


@ Effective input length from the input operation 


® The program name or the symbolic terminal name 


Array 
Element Positions Used 


not used) 












Contents 


e Return code — two decimal characters returned 
by the CCP. 
SPECIAL input operations: Return code is placed 
in positions 3-4. 
SPECIAL output operations: Return code is placed 
in positions 5-6. 


e Operation code — two alphameric characters. 


© Operation modifier — two alphameric characters, 
(optional). 


® Output data length— up to four decimal characters 
(gutput operations). 

Effective input data length — up to four decimal 
characters (returned by CCP on input operations). 

¢Count of outstanding Invite Inputs — a four 
digit decimal number (returned by CCP on release 
terminal operations and when a 08 return code 
occurs on input operations). 

®@Terminal attributes identifier — up to three decimal 
characters (acquire terminal operation only). 


ens ® Maximum input data length — up to four decimal 


characters. 


ee ® Program name or symbolic terminal name — up to six 
| | alphameric characters. 


Note: See Summary — Performing CCP Operations Using RPG 11 SPECIAL Files, \ater in this chapter, for a summary 


of the use of the parameter array. 


Figure 6-1. RPG {1 Parameter Array for SPECIAL Files. 


Because this information is available in the record area, you 
can check the contents of these areas without moving array 
elements into fields. You can also check the input return 
code and effective input length using field indicators. See 
Performing CCP Operations with SPECIAL, later in this 
chapter, for more information about examining the return 
code, effective input length, and terminal name. 


Output Record Area 

On heading, detail, total, or exception (H, D, T, or E) output 
operations, you must place the following information in the 
output record area: 

® Operation code (positions 1-4) 

® Output length (positions 5-8) 


@ Symbolic terminal name, CONSOL, program name, or 
blanks (positions 9-14) 


H, D, T, and E output specifications can be used to issued 
either output or non-I/O operations (such as Release 
Terminal and Invite Input -- for Invite Input, the maximum 
input length must be provided in the parameter array). See 
Performing CCP Operations with SPECIAL, later in this 
chapter, for additional information about setting parameters 
for various operations. 


CCP Communications Service Subroutines for SPECIAL 


Two SPECIAL file subroutines, SUBR92 and SUBR9Q3, are 
provided by the CCP for terminal operations, SUBR92 
is used for processing all requests for terminal operations. 
SUBR@Q3 is used only with a ‘‘false’’ SPECIAL file (see 
Defining SPECIAL Files) in order to bypass the record 
selection part of the RPG I] object program cycle so that 
input operations can be performed in calculations using 
the RPG Il READ operation code. The first entry to 
SUBRQ3 returns to your program without data; all sub- 
sequent entries to SUBR9Q3 cause the end of the file 
condition to be set on for the false SPECIAL file. 
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SPECIAL Input Record Area 
Program or terminal 


name from which 
input was received 


Effective 
input 
Jength 


Previous 
output 


return data 


code 
3-4 





5--\-89-—-—--- 14165----- Ff 


(4096 maximum 


Does not include the end position) 


first 14 positions 


SPECIAL Output Record Area 







Operation 
code 


1 


\ 


Length of data plus 14 


end position) 


Note: See Summary — Performing CCP Operations Using RPG I 
SPECIAL Files, \ater in this chapter, for a summary of the use of 
record areas. 


Figure 6-2. RPG Il Communications Record Area Formats for SPECIAL 
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Figure 6-3. Input Record Area for SPECIAL 
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Figure 6-4, Output Record Area for SPECIAL 


Indicators Reserved for CCP Use 


Indicators 91 and 92 are reserved for use in communica- 
tions operations using the SPECIAL interface. 


SUBR92 sets on indicator 91 when an operation results in 
a negative return code (error condition). SUBR9Q2 sets on 
indicator 92 when an operation results in a positive (greater 
than zero) return code (exception conditions) other than a 
14 return code (the 14 return code indicates a successful 
accept operation of the chain request data). You can use 
these indicators to condition operations in your RPG II 
program. For example, you could use indicators 91 and 92 
to bypass input field moves, calculations, or to execute a 
subroutine that checks return codes when an error or ex- 
ception condition occurs on the previous !/O operation, as 
shown in Figure 6-5. 


If indicator 91 is on when SUBRQ2 receives control to 
perform an operation, the requested operation is ignored 
and control is immediately given back to your program.: 


SUBR9Q2 only sets these indicators on. If your program 
uses indicator 92 to determine whether an exception 
condition occurred, your program must set indicator 92 
off after an exception; otherwise, indicator 92 would re- 
main on until end of job. It is even more important to 
set off indicator 91, because, if it is already on at the time 
a communications operation is issued, the operation is 
not performed, and a return code of -91 is given even 
though the error condition may-no longer exist. 
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DEFINING SPECIAL FILES FOR USE WITH CCP 


One or more SPECIAL files can be defined in File Descrip- 
tion Specifications for use with the CCP. If you are a 
beginning user of the CCP, it may be easier for you to define 
one input and one output file instead of a combined file, 
until you gain familiarity with the use of RPG I for CCP 
operations. Combined files, however, are sometimes more 
economical in their use of main storage and are the only 
file types allowed with the Put-Then-Get operation. Com- 
bined files are more economical of main storage if the 

size of the input and output are approximately the same. 
Separate files should be used (possibly sharing the same 
parameter array) if there is a significant difference (53 or 
more positions) between the sizes of the two record areas. 


Two File Description Specifications are required to define 
each SPECIAL file to be used with the CCP, a main file 
statement and a continuation statement. Figure 6-6 

shows the valid ways of defining a SPECIAL file. Columns 
that are unshaded in the figure have valid required or 
optional entries. 


Note: As shown in Figure 6-6, a continuation specification 
is not required for a ‘‘false’’ SPECIAL file (using SUBR93), 
since a parameter array is not required. 
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Figure 6-5. Using Reserved Indicators 91 and 92 (SPECIAL Only) 
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Figure 6-6. Valid Methods of Defining a SPECIAL File for CCP Operations 


Main File Description for SPECIAL 


Page and Line (1-5): See RPG // Reference Manual, 
$C21-7504, 


Form Type (6): The preprinted character F identifies this 
as a file description specification. 


Filename (7-14): Enter a name for the CCP SPECIAL 
file. Use this name to refer to the SPECIAL file - not to a 
specific terminal - in subsequent Input, Calculation, and 
Output Specifications. Rules for forming filenames are 
given in the APG // Reference Manual, SC21-7504. 


File Type (15): 1,0, and C are valid entries in this column. 
See combinations on Figure 6-6 for valid File Type/File 
Designation entries. 


File Designation (16): P,.S, D, and blank are valid entries 
in this column. See Figure 6-6 for valid combinations of 
File Type/File Designation entries. 


End of File (17): E is avalid entry with Input and Combined 
files which are designated as primary or secondary. Leave 
this column blank if you need not process terminal input 
data to End of File. When using a false SPECIAL. file, set 
End of File to on during the second and subsequent entries 
to SUBR93. When using a SPECIAL file with SUBR92, you 
must set the End of File condition by issuing the Force 

End of File operation, even though you may have entered 
an E in this column (see CCP Operation Codes, \ater in 

this chapter, for an explanation of the Force End of File 
operation). 


Sequence (18): See RPG II Reference Manual. 


File Format (19); Enter an F or leave blank (RPG II 
assumes F). Files must be defined as having fixed-length 
records, even though variable length records can be handled 
via the CCP (see Record Length and index entry variable 
length records). 


Block Length (20-23): Enter the same value specified in 
columns 24-27 (record length), or leave these columns blank. 
If you specify a block length greater than record length, 

you will add unnecessary space to your program. Blocking 
is allowed with BSCA terminals (see index entry b/ocking), 
but is specified during CCP assignment (see TERMATTR 
statement in CCP System Reference Manual). 
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Record Length (24-27): Enter a value equal to the maximum 
size record or message you expect to receive or send, plus 

14. The extra positions are required for the input/output 
parameters and terminal name in the first 14 positions of 

the record area. (Additional information must be provided 
in the record area for certain 3270 Display Format Facility 
operations — see index entry.) For SUBR93, a record 

length of 7 is suggested. 


Columns 28-39: Leave these columns blank. 
Device (40-46): Enter SPECIAL. 
Columns 47-53: Leave these columns blank. 


Name of Label Exit (54-59): Enter SUBRQ2 for all 
SPECIAL files to be used for communicating with terminals. 
Enter SUBR93 only if you are defining a fa/se file in 

order to bypass RPG II record selection logic when using 
demand files (see Figure 6-6). See Programming Examples 
later in this chapter for an example of using SUBRQ3. 


Columns 60-74; Leave these columns blank. 


Continuation Specification for SPECIAL 


A continuation specification must follow each SPECIAL 
file description, except for a fa/se SPECIAL file. The 
purpose of the continuation line is to associate an array 
with the SPECIAL file, to be used as a parameter list for 
communicating with terminals via the SPECIAL file. 


Form Type (6): The preprinted character F identifies this 
as a file description specification. 


Columns 7-52: Leave these columns blank. 
Column 53: Enter K (continuation). 


Operation (54-59): Enter the name of the array that is to 
be used to pass parameters to the subroutine defined in 
the previous SPECIAL file description. This array must 
be defined in Extension Specifications. 


DEFINING THE PARAMETER ARRAY 


One Extension Specification must be provided for each 
array associated with a SPECIAL file (SUBR9Q2) in File 
Description Specifications and for each array used with 
EXIT/RLABL (see EX/T/RLABL Communications Inter- 
face). You may use one array for both SPECIAL files and 
EXIT/RLABL processing; EXIT/RLABL subroutines 
SUBRQ11 disregards the fifth element. 


You can use the same parameter array for more than one 
SPECIAL file. Whether you use the same array or separate 
arrays for different SPECIAL files can be determined by 
which is most convenient for your program. 


You can load the parameter array at compilation time, 
pre-execution time, or during execution (Figure 6-7). Com- 
pilation time arrays are most efficient in terms of the 
amount of RPG II object code generated. You should load 
the array at compilation time or pre-execution time if it is 
to be used with a primary or secondary SPECIAL file, so 
that the proper operation code and maximum input length 
are in the array when the file is read on the first program 
cycle. See APG // Reference Manual, SC21-7504, or RPG 
M Additional Topics, GC21-7567, for a complete descrip- 
tion of loading and defining arrays. 


Note: If the array is a pre-execution time array, the card 
input device or disk file used to load the array is allocated 
to the program until end of job. The card device or disk 
file must be defined on the // PROGRAM assignment 
statement. 


Extension Specifications 


Page and Line (1-5): See RPG I! Reference Manual, 
$C21-7504. 


Form Type (6): The preprinted character E identifies this 
as an extension specification. 


Columns 7-10: Leave these columns blank. 


From Filename (11-78): \f the array is to be loaded at 
pre-execution time, enter the name of the file from which 
it is to be loaded. 


Columns 19-26: Leave these columns blank. 


Array Name (27-32): Enter the name of an array which is 
described on a File Description Continuation Specification 
with a SPECIAL file or which is used as an RLABL follow- 
ing an EXIT operation. Rules for forming array names are 
given in the APG // Reference Manual, SC21-7504. 


' Number of Entries Per Record (33-35): Make an entry in 


these columns only for compilation time and pre-execution 
time arrays. Enter 008 for arrays used with SPECIAL files 
and SUBR9Q2; enter 004 for arrays used only with EXIT/ 
RLABL. When loading an array at compilation time or 
pre-execution time, the entire array must be loaded from 

a single record. An entry is required in these columns when 
using primary or secondary files with SUBR92, since you 
must use a compilation time or pre-execution time array to 
provide parameters for the first operation. 


Number of Entries Per Array (36-39): Enter 0005 for 
arrays used with SPECIAL files and SUBR92; enter 0004 
for arrays used only with EXIT/RLABL. 


Length of Entry (40-42); Enter 006,.the length of array 
elements. 


Extension Specifications 
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Figure 6-7. Entries Required to Define Parameter Arrays Used with CCP SPECIAL Files and EXIT/RLABL Operations 
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Columns 43-74: Leave these columns blank. Note that 
the array must be defined as alphameric. 


CCP OPERATION CODES 


The RPG UI form of the CCP operation codes for SPECIAL 
and EXIT/RLABL communications operations is composed 
of two parts. The rightmost two characters of the operation 
code define the basic operation to be performed. The valid 
RPG II operation code/modifier combinations are summar- 
ized in Appendix D. See Chapter 8: 3270 Display Format 
Facility for additional operations and operation codes that 
_are used only with the DFF. 


The valid CCP operation codes for RPG II are: 


Code Meaning 
00 Shutdown Inquiry 
bA Get (For Stop Invite Input see 


modifier Code D below) 


AA Get and Reverse Interrupt 

GA Force End of File 

6B Put 

BB Put Block 

DB Copy (DFF only) 

EB Erase All Unprotected (DFF only) 
FB Put Block — PRUF 

CB Put Message 

GB Put Message — PRUF 

Cc Combined Put (Record)-Then-Get 
cc Put (Message)-Then-Get 

’D Accept Input 

BE Invite Input 

BF Put-No-Wait 

BF Put-No-Wait Block 

CF Put-No-Wait Message 
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Code 


GF 


bH 


bl 


Al 


BI 


bK 
AK 
BK 
cs 


bw 


Meaning 
Put-No-Wait Message — PRUF 
Get Terminal! Attributes 


Acquire Terminal (with present 
attributes) 


Acquire Terminal (with new 
attributes) 


Acquire a command-mode 
non-DFF terminal 


Release Terminal (and release line) 
Release Terminal (keep line) 
Chain Task Request 

Put (Message) with Invite Input 


Put-No-Wait (Message) with Invite 
Input 


The valid operation modifiers for RPG II are: 


Code 


be 


bA 


bB 


bc 


bD 


6H - 


Meaning 


Perform carriage-returns at start of 
data and at end of data for MLTA 
typewriter terminals. (See index 
entries new /ine and end line) 


Perform a carriage-return at start of 
data, not at end of data. 


Perform a carriage-return at end of 
data, not at start of data. 


Do not perform carriage-return. 


Stop an Invite Input for this terminal. 
This modifier is only valid with the 
Get operation code, that is ‘DBA’. 
(See index entry stop invite input.) 


Override (modify) format fields (DFF 
only -- used with operation codes CB, 
GB, CF, GF, CS, and #W). 


Descriptions of the operations listed above are given under 
Operations in Chapter 2 and under Display Format Facility 
Operations in Chapter 8, except for the following three 
operations, which are used only with the RPG I] SPECIAL 
interface: Force End of File, Put with Invite Input, and 
Put-No-Wait with Invite Input. 


Force End of File (SPECIAL Only) 


When using a primary or secondary SPECIAL file, for 
communications operations, you may need to inform the 
communications service subroutine (GSUBR92) when to set 
on an end of file indication in order to cause another 
secondary file to be processed or to cause your RPG II 
program to perform LR logic. To issue a Force End of 
File operation, you need only set the operation code in 
the second array element (if issued as an input operation) 


or in the output record area (if issued as an output operation). 


CCP does not return a return code for this operation. The 
information in the parameter list is not changed by this 
operation. 


Force End of File cannot be issued using EXIT/RLABL and 
cannot be issued to the ‘‘False’’ SPECIAL file (SUBR9Q3). 
The “False” SPECIAL file will be set at end of file after 

the second access of the file. 


Put With Invite Input (SPECIAL Only) 


Put with Invite Input is the equivalent of a Put Message 
operation (treated as Put Record for MLTA terminals} 
followed by Invite Input to the same terminal. This opera- 
tion allows you to issue a Put and an Invite Input via H, D, 
T, or E output specifications in a single operation. To issue 
this operation, place the maximum input length for the 
Invite Input into the fourth element of the parameter array 
(if not there already) and place the following parameters in 
the output record area: 


® Operation code ‘6KCS’ (‘BHCS', if DFF overrides are 
being put) 


® Output length for the Put 
@ Symbolic terminal name 


If Put with Invite Input is being issued at detail output 

time, the operation code for Accept Input (‘#D‘) must be 
placed in the second element of the parameter array prior 

to issuing the Put. This allows the program to accept data at 
the next input time in the RPG II cycle. 


The CCP places the return code for this operation in the 
parameter list and sets on indicator 91 or 92 if an error or 
exception condition results from the operation. The return 
code and indicators reflect only the result of the Put portion 
of the operation. If indicator 91 is on after the operation, 
the Invite Input (and Accept Input, if issued) will have 

been ignored and a -91 return code returned to your program. 


When you want to Put a message to a terminal and Invite 
additional input from the.terminal, you can save coding 
and possibly save an unnecessary pass through the RPG II 
logic cycle by using Put with Invite Input. 


Put-No-Wait With Invite Input (SPECIAL Only) 


The function and use of Put-No-Wait with Invite Input 
are the same as Put with Invite Input, except that after 
the CCP has accepted the operation, your program does 
not wait for, and does not receive a return code. The 
operation code is ‘BAW’ (‘BHBW’, if DFF overrides are 
being put). 


If indicator 91 is on after the operation, the Invite Input 
(and Accept Input, if issued) will have been ignored and a 
-91 return code returned to your program. 


PERFORMING CCP OPERATIONS WITH SPECIAL 


Performing a CCP communications operation using 
SPECIAL involves one or more of the following steps. 
The specific steps required depend on which operation 
is being issued and whether the operation is issued as an 
input operation (primary, secondary, or demand input) 
or an output operation (H, D, T, or E output): 


1 Set the parameters for the operation in the proper 
location in the parameter array (input) or record 
area (output). 


2. Specify the name of the program for a chain task re- 
quest or the symbolic terminal name for the opera- 
tion, if required, in the parameter array (input) or 
record area (output). 


3. Place any data to be transmitted in the record area 
(output operations). 


4. Issue the operation during output or input time in 
the RPG I! program cycle (via Output or Input 
specifications) or, if demand input or exception out- 
put are used, issue a READ or EXCPT operation in 
calculations to perform the operation. 
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5. Check the result of the operation by testing the 
return code and/or using indicators 91 and 92. 


6. Examine and/or process other returned information, 
such as the effective input length (if a data truncated 
return code is received), symbolic terminal name, and 
input data. 


Operations that involve transfer of either input or output 
data are restricted to being issued either as input or output 
operations, since either an input or output record area must 
be provided. The following operations must be issued as 
primary, secondary, or demand input operations via a 
SPECIAL input or combined file: 


@ Get 


Accept Input 

® Stop Invite Input (may result in a Get) 

@ Get Attributes 

The following operations must be issued as output opera- 
tions, using H, D, T, or E Output Specifications via a 
SPECIAL output or combined file: 

@ Put 

@ Put-No-Wait 

® Put with Invite Input 

@ Put-No-Wait with Invite Input 

® Copy (DFF) 

®@ Chain Task Request 

@ Erase All Unprotected (DFF) 

The following operations can be issued as either input or 
output operations, since they do not result in transfer of 


data: 


@ Acquire Terminal 


Invite Input 


Shutdown Inquiry 


Force End of File 


Release Terminal 
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Of these operations, Acquire Terminal, Invite Input, and 
Shutdown Inquiry are most logically issued as output 
operations; Force End of File is most logically issued as an 
input operation. (See Non-//O Operations, later in this 
section.) 


The Put-Then-Get operation, which can be used only with 
combined SPECIAL files, is both an input and output 
operation and requires both an input and an output record 
area (see Put-Then-Get Operation, later in this section). 


Performing CCP Operations Using Primary, Secondary, 
or Demand Input 


To cause an operation to be performed during primary, 
secondary, or demand input time in the RPG II program 
cycle, provide an input record area in the appropriate 
format (Figure 6-2 and 6-3) and place the following 
information in the parameter array: 


1 

2 Operation 

3 

4 Maximum Input Length 
5 Symbolic Terminal Name 





When using a primary or secondary SPECIAL file, this 
information must be placed in the array prior to the first 
read from the file. Therefore, you should load the array 

at either compilation time or pre-execution time with the 
appropriate information for the first operation. For sub- 
sequent operations from the file, if any of the array contents 
must be changed, they can be reset in calculations, as shown 
in Figure 6-8. 


In some applications, it is not convenient to perform input 
Operations at primary or secondary input time in the RPG 
I! cycle. Using a demand file, you have more control over 
when the file is read, since you cause the file to be read 
whenever you issue the READ operation in calculations. 
Therefore, demand files are more flexible for communicat- 
ing interactively with terminals. 
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Figure 6-8. Setting the Parameter Array Contents for a Primary, Secondary, or Demand Input Operation 


If the file is used for a series of operations, you may not 
need to modify all parameter array elements for every 
operation. 


Operation Code 


In setting or modifying the operation code, you can avoid 
having an invalid operation code/modifier combination by 
always moving both parts of the operation code into the 
parameter array, as is done in Figure 6-8. (See Put-Then- 
Get Operation, later in this section, for special considera- 
tions.) 


Maximum Input Data Length 


For operations that can result in input data being received 
in the input record area (Get, Accept Input, Get Attributes, 
and Stop Invite Input), set the fourth element of the para- 
meter array to indicate the maximum amount of data you 
expect from a terminal, including device control characters 
your program handles (see index entry device contro/ 
characters) and including the 14 characters reserved in the 
record area for CCP use. The maximum number you can 
enter is 4096. 


For the Get Attributes operation, set the value of the 
fourth array element to 35, the length of the attributes 
data (21) plus the required information in the first 14 
positions of the record area. 


This element of the parameter array is never modified by 
the CCP; therefore, as long as your maximum input length 
remains the same, you need not reset this element. 


Symbolic Terminal Name 


You must place the symbolic termina! name (or blanks) 
in the fifth array element when you issue one of the 
following operations at primary, secondary, or demand 
input time: 


@ Get 

@ Invite Input 

@ Stop Invite input 
©@ Get Attributes 


You can use blanks in the fifth array element for these 
operations only in single requesting terminal (SRT) pro- 
grams (see index entry). When you use a blank terminal 
name, the CCP returns the name of the terminal that 
requested the program in the input record area and in the 
parameter array after the operation. 


You need not specify a name for the Accept Input opera- 
tion; however, after the operation, the CCP places the name 
of the program or terminal from which the input data was 
received in the fifth element of the parameter array and in 
the record area, 
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See Put-Then-Get Operation, later in this section, for 
special considerations. 


Testing the Return Code 


After any CCP operation, you should test the return code 
to determine the result of the operation, since the result 
may require special actions in your program. If the opera- 
tion resulted in an error condition (negative return code) 
or exception condition (positive return code), you might 
either take specific actions in your program or inform the 
system operator of the condition by issuing a message to 
the console. 


The CCP places the return code for input operations issued 
at primary, secondary, or demand input time in the first 
two positions of the input record area as well as in the 
middle two positions of the first element of the parameter 
array (see Figures 6-1 and 6-2), The return code for the 
last output operation is availabie in positions 5-6 of the 
first array element and in positions 3-4 of the input record 
area. Also, the CCP sets on indicators 91 and 92 for error 
and exception conditions, respectively (see /ndicators 
Reserved for CCP Use). Thus, you can test return codes 
in a variety of ways: 


@ Using Calculations to test the contents of the return 
code field in the input record area. 


@ Using indicators 91 and 92 to condition operations in 
Calculations and to condition output lines (Figure 6-5). 


@ Using record identification codes or field indicators 
on Input Specifications. 


Figure 6-9 shows an example of testing the return code 
for plus, minus, or zero by means of a compare operation 
and resulting indicators. If you wish, you can test for the 
exact return code to determine which exception or error 
condition occurred and take appropriate action, Return 
codes and recommended program actions are summarized 
in Appendix E. 


If indicator 91 is on when any input operation is requested, 
the operation is ignored by SUBR9Q2 and a return code of 
-91 is returned (appears as 9J). This return code may be 
used to prevent blanking out of previous input fields (see 
Figure 6-10). 


Figure 6-10 shows how indicators may be set on for input 
operations with SPECIAL files to indicate record type, 
normal completion, error or exception return code. In this 
example, the record NAM is read with indicator 01; the 
record ADR is read with indicator 02. If there is nota 


normal completion of the input operation, indicator 03 is 
on, the return code is moved into a two-character numeric 
field (RTNCOD) for more detailed testing in calculations. 


Special considerations are involved when you use the input 
return code from positions 3 and 4 of the first element of 
the array. If the correct sequence of operations Is not 
followed, the sign of the input return code can be lost. 

The procedure requires that the first element be moved into 
a four-position alphameric field via a MOVEL Instruction, 
and that the same four-position field be moved into a two- 
position field via a MOVE instruction. The two-position 
field then contains the input return code with the correct 
sign. 


Although it is possible to do preliminary return code 
checking using the method shown in Figure 6-10, that 
method is not recommended, since it is much easier to 
detect positive and negative return codes using indicators 
91 and 92. 


Examining the Effective Input Length 


On SPECIAL input operations, the CCP returns the effective 
input length in positions 5-8 of the input record area 

(Figure 6-2), This value includes only the actual length 

of data available to your program and does not include the 
14 characters preceding the data in the record area or the 
length of truncated data. The input data begins in position 
15 of the record area. 


After you have issued an input operation, you can examine 
the effective input length, for example, to verify that the 
terminal entered a required number of characters, in order 
to detect erroneous input. You might also use the value of 
the effective input length as the limiting value in a routine 
that scans the input data. 


The effective input length may be equal to or less than the 
maximum input Jength you specified for the operation, 
depending on the actual amount of data transmitted to 
your program by a terminal. If the terminal transmits more 
data than the maximum you specified, the excess data is 
truncated and your program receives a “data truncated” 
return code. (See index entry data truncated, special use 

in DFF, for a special meaning of the data truncated return 
code.) 


Contents of the effective input length field for each opera- 
tion code and return code is summarized in Appendix E 
(Table E-7). 
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Figure 6-9. Using Calculations to Test the Return Code in the SPECIAL Input Record Area 


Examining a Returned Name 


For the Accept Input operation and for operations issued 
with a blank name field, CCP returns the program name or 
a symbolic terminal name to your program (see index entry 
operations). For all operations issued at primary, second- 
ary, or demand input time, the CCP places this name in 
positions 9-14 of the input record area. You may need to 
examine this name to determine which program or termi- 
nal is communicating with your program. 


For example, in a mu/tiple requesting terminal (MRT) pro- 
gram (see index entry), you should examine the terminal 
name you receive from an Accept Input operation in order 
to determine if the terminal is a new requester or if it is 
already attached to your program. If the terminal is a 
new requester, you might move the terminal name toa 
save area. If the terminal has previously provided input to 
your program, you may need to associate new data with 
data previously received by comparing the terminal name 
with a saved terminal name. Example 2 under Programming 
Examples shows an example of examining the terminal 
name after an Accept Input operation. 


If a program can be requested from both a terminal and an- 
other program using the Chain Task Request operation, you 
may want to determine how the program was requested. 
This can be accomplished by checking for a 14 return code, 
indicating a Chain Task Request operation. This informa- 
tion is useful if a program communicates with the requestor 
since your program cannot communicate with a chain task 
requesting program. 


Performing CCP Operations Using Heading, Detail, Total 
or Exception Output 


When issuing CCP output operations at H, D, T, or E out- 
put time via a SPECIAL output or combined file, you 
must place the operation code, output jength, and ihe 
program or terminal name in the output record area, as 
shown in Figures 6-2 and 6-4. 


The output length for SPECIAL output operations includes 
the 14 positions required in the record area for the opera- 
tion code, output length, and terminal name. This length 
also includes device control characters you are inserting 
yourself and the special information required for certain 
3270 DFF operations. Thus, the value of the highest end 
position used on the Output Specifications should be used 
as the output length. The maximum length is 4096. 


After an operation is performed at H, D, T, or E output 
time, the CCP places the return code in positions 5-6 of the 
first element of the parameter array (Figure 6-1). You can 
easily test the return code for a positive or negative value 
by using indicators 91 and 92 (see /ndicators Reserved for 
CCP Use, earlier in this chapter). In order to test for a 
specific return code value, however, you must move the 
contents of the first array element to a two-position 
numeric field. Figure 6-11 shows how these methods can 
be used in combination to test the return code. See 
Programming Examples, later in this chapter, for additional 
examples of testing return codes. 
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Figure 6-10. Testing the Return Code on Input Specifications (SPECIAL Input Operation) 


When performing operations via H, D, T, or E output, you @ On SPECIAL output operations issued with a blank 
need only use the parameter list in the following cases: terminal name (valid for SRT programs only), the CCP 

returns the name of the requesting terminal in the fifth 
@ To test the return code in positions 5-6 of the first element. 





element after the operation. 

Note: \f a valid terminal name is given in the output record 

® To check the count of outstanding Invite Inputs in the area for a SPECIAL output operation, any name in the 
third array element after issuing a Release Terminal fifth element of the parameter array is not modified. 
operation at output time. 


® To specify the maximum input length value in the 
fourth element when issuing an Invite Input operation 
at output time (see Won-//O Operations, later in this 
section), 
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Figure 6-11. Example of Return Code Testing After a SPECIAL Output Operation 


Exception Output 


To perform exception output to a specific terminal (via a 
SPECIAL output or combined file), place the appropriate 
operation code, output length, and program or terminal 
name in the output record area (Figure 6-2 and 6-4), and 
issue the EXCPT operation in calculations. If the program 
or terminal name is less than six characters long, it must 
be left-justified and padded with blanks in the name field 
of the output record area. 


Exception output enables you to check the return code in 


calculations immediately after performing the EXCPT 
operation. 


RPG Il 6-17 


If you are sending multiple lines of output to one terminal, 
or single lines to more than one terminal during any one 
EXCPT operation, you can check the return code for only 
the last operation (last line of output). Therefore, it is 
suggested that one output record be sent to only one 
terminal by each EXCPT operation. This can be controlled 
through the use of indicators. 


See Programming Examples, Example 2, later in this 
chapter, for examples of exception output. 


Heading, Detail or Total Output 


In general, using H, D, or T output to issue CCP operations 
is similar to using exception output, in that the operation 
code, output length, and terminal name are placed in the 
output record area rather than in the parameter array and 
several lines of data can be sent to the same or different 
terminals on each program cycle. 


You must be aware that when you send several lines of 
output to the same SPECIAL output file using H, D, or 
T output, the return code in the parameter list applies 
only to the last output line. Therefore, you have no way 
of knowing when an exception condition occurred on 
output lines previous to the last output line. Also, when 
an error occurs, you have no way of knowing on which 
output line the error occurred. 


See Programming Examples, Example 1, and the MRT 
Programming Example Using the Display Format Facility 
in Chapter 8 for examples of H, W, and T output lines. 


Put-Then-Get Operation 
The Put-Then-Get operation must be issued with a combined 
SPECIAL file. The operation is not actually performed 


via SUBRQ2 until the input part of the combined operation 
is performed, 
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Combined Demand Input/Exception Output File 
Perform the Put-Then-Get operation as follows: 


1. Place the maximum input length in the parameter 
array. 


2. Place the following information in the output record 
area: 


@ Put-Then-Get operation code (positions 1-4) 
@ Output length (positions 5-8) 
@ Symbolic terminal name (positions 9-14) 

3. Issue an EXCPT operation. 

4, Issue a READ operation. 


After you issue the READ operation, the input data is 
available in the input record area. You need not provide 
a terminal name or operation code in the parameter 
array for the READ, since SUBR9Q2 assumes that the first 
input operation for a combined file following the Put 
part of a Put-Then-Get to the file is the Get part of the 
operation from the same terminal. 


When issuing a Put-Then-Get to a terminal using EXCPT 
and READ, you may do output to other terminals after 
doing the output part of the combined operation. If 
successive Put-Then-Get operations are performed to the 
same or different terminals using the same SPECIAL file 
before doing the input part of the combined operation, 
then only the last output will be sent to the terminal. 


See Programming Examples, Example 2, for an example 
of using READ and EXCPT to issue a Put-Then-Get opera- 
tion. 


Combined Primary or Secondary Input/H, D, or T 
Output File 


You can also issue a Put-Then-Get operation using H, D, 
or T output and primary or secondary input with a 
combined SPECIAL file. Place the maximum input length 
in the parameter array for the combined SPECIAL file. 
Place the following information in the output record area: 
@ Put-Then-Get operation code (positions 1-4) 


® Output length (positions 5-8) 


® Symbolic terminal name (positions 9-14) 


The input data from the Put-Then-Get is available in the 
input record area after Primary or Secondary input in the 
RPG I} cycle. You need not provide a terminal name or 
operation code parameter array for the input part of the 
combined operation, since SUBR92 assumes that the first 
input from the file is the input part of the operation for the 
same terminal. 


Considerations for performing other output operations after 
the output part of the combined operation and for perform- 
ing successive Put-Then-Get operations are the same as 
described for EXCPT and READ. 


Testing the Return Code After a Put-Then-Get 


The return code from a Put-Then-Get is placed in 
positions 3-4 of the first array element. Positions 5-6 

of the first array element will be zero if the last output 
operation was the Put part of this combined operation. 

If an error condition resulted from the operation (this 
can be determined using indicator 91) you can determine 
whether the error occurred on the Put or on the Get by 
testing the value in the third array element. If this value 
is the sarrie as the output length specified for the Put-Then- 
Get, then the error occurred on the Put portion of the 
operation (the Get was not performed). If the value of 
the third array element is different from the output 
length specified for the operation, then the error occurred 
on the Get. 


Note Concerning the Use of Put-Then-Get 


The typical use for Put-Then-Get is to issue a message to 
the system operator (CONSOL) and receive instructions. 
In an MRT program, the need to modify the parameter 
list can be minimized by initializing the array for the 
combined file with the ‘4D’ operation code (Accept 
Input), a blank terminal name, and the maximum input 
length used by the program. Thus, when the Put-Then- 
Get operation is issued, the array need not be modified 
in order to continue with normal operation, since the Put- 
Then-Get operation code was given in the output record 
area. 


Non-1/O Operations 


Non-I/O operations can be issued at either input time 

(primary, secondary, or demand) or at output time (H, 
D, T, or E), since they do not result in transfer of data 
to or from your program. The non-!/O operations are: 


® Acquire Terminal 


Release Terminal 


Invite Input 


Shutdown Inquiry 


Force End of File 


When issued via SPECIAL files, Acquire Terminal, Release 
Terminal, Invite Input, and Shutdown Inquiry are most 
logically issued as output operations; Force End of File 

is most logically issued as an input operation. 


When you issue non-I/O operations at input time using 
SPECIAL files, you must provide a “dummy” input specifi- 
cation to avoid getting an UNIDENTIFIED RECORD 

halt, since RPG [I assumes that valid data is contained in 
your input record area after the operation. See Program- 
ming Examples, Example 2, for an example of a “dummy” 
input specification. 


While all of the non-I/O operations can be issued using 
SPECIAL files, it is also convenient to use EXIT/RLABL 
for these operations, since no input or output record area 
is required and there is no requirement for RPG II to 

move input of output fields. You must be aware, however, 
that using both SPECIAL and EXIT/RLABL for CCP 
operations increases the main storage requirement of your 
program, This can be an important consideration in some 
cases, 
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SUMMARY — PERFORMING CCP OPERATIONS USING RPG It SPECIAL FILES 
(see notes on opposite page) 


INPUT RECORD AREA 


Input Return} Output Return | 1. Effective Input Length Program or 
2. #Outstanding Invite Inputs | Symbolic Terminal Name 





PARAMETER ARRAY 






Return Code Operation Code/ 1. Effective Input Length Maximum Expected Program or 
Modifier 2. Attributes ID Input Length Symbolic Terminal 
3. #Outstanding Invite Name 





OUTPUT RECORD AREA 











Program or 
Symbolic Terminal Name 


Operation 
Code 


Operation 
Modifier 


1. Output Length 
2. Attributes 1D 





Operations Issued at Input Time 


Information Supplied by Programmer: 

il Place the operation code here before issuing the 
operation. Exception: On a Put-Then-Get operation, 
this element is disregarded on the Get portion of the 
operation. Upon completion of the operation, this 
element remains unchanged. 


I Place the maximum expected input length here 
before issuing the operation (includes the first 14 
positions in the record area). Upon completion of 
the operation, this element remains unchanged. 


6-20 


| Place the symbolic terminal name here prior to 
issuing the operation. Exception: 


1. Accept Input -- contents are ignored by the CCP 


2. Blanks - CCP assumes the requesting terminal 
(SRT programs) 


3. Shutdown Inquiry -- contents are ignored by 
the CCP 


This element is changed after Accept Input or a blank 
terminal name is used. Exception: When a Put-Then- 
Get is issued with a blank terminal name, the name of 
the requesting terminal is returned only in positions 
9-14 of the input record area. 


Information Returned by CCP: 


I 1. 
3 


Contains the effective input length (not 
including the first 14 positions), after an 
input operation (Get, Accept Input, Put-Then- 
Get, Get Terminal Attributes, and Stop Invite 
Input that fails to stop input.) 


2. Contains the count of outstanding Invite Inputs 
when: 


a. A Release Terminal operation is issued 
b, A 08 return code was received 


I Input operation return code. 


I Return code from the last output operation using this 
array. 


\ If the 3270 Display Format Facility is used, position 
15 contains the AID character, except when data is 
received with the program request on systems without 
Program Request Under Format (PRUF). 


IZ After an Accept Input operation, Put-Then-Get 
operation, or an operation issued with a blank 
terminal name, the CCP returns a symbolic terminal 
name or for an Accept !nput in a program loaded by 
a Chain Task Request, the name of the program that 
issued the Chain Task Request operation in these 
positions. 


Operations Issued at Output Time 
Information Supplied by Programmer: 


O Place the operation code here prior to issuing the 
operation. 


0, Place the output length here for output operations 
(include the first 14 positions of the record area). 
Place the attributes identifier here for Acquire termi- 
nal with Set Terminal Attributes modifier. CCP 
ignores the contents of this field for Release Termi- 
nal, Invite Input, Shutdown Inquiry, and Acquire 
Terminal without Set Terminal Attributes modifier. 


Oy Place the requested program name, the symbolic 
terminal name, blanks, or CONSOL here. This entry 
is ignored for Shutdown Inquiry. 


Information Returned by CCP: 
O3 Output operation return code. 


O4 These elements are unchanged after the output 
operation, Place the maximum input length in the 
fourth array element prior to issuing Invite Input, 
Put with Invite Input, Put-No-Wait with Invite Input, 
and Put-Then-Get. 


O5 After the Release Terminal operation, this element 
contains the count of outstanding Invite Inputs. 


Og CCP returns the symbolic terminal name in this 
element after operations issued with a blank terminal 
name, except Put-Then-Get. On Put-Then-Get opera- 
tions issued with a blank terminal name, CCP returns 
the symbolic terminal name in positions 9-14 of the 
input record area after the Get portion of the opera- 
tion is performed. 


O7 If the Display Format Facility is used, positions 15-20 
contain the format name for the Put Message operation; 
position 15 contains the Write Control Character 
for the Put Overrides operation. 


EXIT/RLABL COMMUNICATIONS INTERFACE 


All of the CCP operations described under Operations in 
Chapter 2 can be performed using EXIT/RLABL. CCP 
provides four subroutines for use with EXIT: SUBR91, 
which can be used for all communications operations in- 
cluding task chain request operations; SUBR90, which can 
be used to move fields to or from a record area; SUBR87, 
which is used to issue Chain Task Request operations only; 
and SUBR88, which is used to accept both program request 
and chain task data. SUBR87 and SUBR88 are best suited 
for programs that are primarily used for task chaining 
operations. 


Note: You must not use SPECIAL subroutines SUBR92 
and SUBR93 with EXIT/RLABL. 
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Parameter Array 


As with the SPECIAL interface, you must place the para- 
meters for an operation in a parameter array. The format 
of the parameter array for EXIT/RLABL (Figure 6-12) is 
the same as for SPECIAL, except as follows: 


@ CCP always places the return code from an operation 
in positions 5-6 of the first array element, not in the 
record area. 


@ The program name or the symbolic terminal name is 
always in the record area. Therefore, you may define 
an array of four elements if you are using the array only 
for EXIT/RLABL. You can use the same array for both 
SPECIAL and EX!T/RLABL if the array has five 
elements. 


The Extension Specifications for defining parameter arrays 
are described in Defining the Parameter Array, previously 
in this chapter. 


Record Area 


The record area for communications operations using 
EX!IT/RLABL must be defined by an RLABL in calcula- 
tions (see EX/T to SUBR91). The record area (Figure 
6-13) consists of the name field and a data area. Note 
that the format is different from the record area for 
SPECIAL. 


EXIT to SUBR91 
The linkage to SUBR9Q1 to perform a CCP operation in- 


volves an EXIT operation followed by two RLABLs, as 
follows: 
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The first RLABL is the name of an array (ARY, for 
example) which is used as a parameter list by SUBR91. It 
may be the same array as used for a SPECIAL file, except 
that the fifth element is not used. See Defining the 
Parameter Array, earlier in this chapter. 


The second RLABL is the record area. The first six posi- 
tions of this area must contain the program name or the 
symbolic terminal name for which an operation is intended, 
followed immediately by the data to be sent or received 

to or from a terminal. Since this data may consist of 

many fields, the CCP provides another EXIT subroutine, 
SUBR9O, to move fields to or from the record area (see 
EXIT to SUBR90). 


The size of the record area should be large enough to con- 
tain the maximum amount of data to be sent or received 
plus the six characters for the name field. If the largest 
amount of data to be sent or received is greater than 256 
{including the name field, then an array must be defined 
for this area, since the maximum size of an RPG II alpha 
field is 256. Thus, if 800 characters are needed (for 
example with a 3270 Display) plus the symbolic name 

{a total of 806), an array could be defined containing four 
elements of 202 characters each. This would create a 
contiguous area of core of 808 bytes, which is large 
enough. If an array is defined as the record area for 
EXIT/RLABL linkage, the second RLABL must be a 
reference to the first element of the array: 
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Figure 6-12. 


Array 
Element 


Positions Used Contents 


- not used) 





( 


decimal character $s 


returned by CCP fol- 
lowing operation (zero, 
positive, or negative). 





Operation code — two 
alphameric characters. 





Operation modifier — 
two alphameric charac- 
ters (optional). 


Output data length — 
up to four decimal 
characters (output 
operations). 

Effective input data 
length — up to four - 
decimal characters 
(returned by CCP on 
input operations. 
Count of outstanding 
Invite Inputs — a four 
digit-decimal number 
(returned by CCP on 
release terminal oper- 
ations and when a 08 
return occurs on input 
operations. 

Terminal attributes 
identifier — up to four 
decimal characters 
(acquire terminal op- 
eration only). 


Maximum input data 


length — up to four 
decimal characters. 


® 


RPG II Parameter Array for EXIT/RLABL 


1 6°7 n 
(4096 maximum, including the terminal name} 


Figure 6-13. Record Area Format for EXIT/RLABL CCP Interface 


Setting the Parameters for an Operation 


Issuing a non-I/O operation (such as Release Terminal) in- 
volves simply setting the contents of the parameter array 
with MOVE instructions and placing the terminal name 

in the record area. Since only the terminal name is required 
in the record area for non-I/O operations, you can issue 

the operation as shown in the following example, specifying 
a field that contains the terminal name as the second 
RLABL. 


—-| 


Factor 4 


RPG CALCULATION SPECIFICATIONS 








Punching 


Graphic Card Electro Number 
Instruction | punch Pe 


Result Field 


Factor 2 


Operation 


& Decimal Positions 


48 19 20 21 22 23 24 25 26 27428 29 30 31 32|33 34 35 36 37 38 39 40 41 42/43 44 45 46 47 48]49 50 51 





















































































































































If, however, you are issuing an operation that involves a 
number of fields of input or output data, you will need 
to use SUBR90 to move fields to or from the record area, 
since there is no facility in RPG !| Calculations to move 
fields to or from various section of another data field. (A 
series of MOVE or MOVEL operations could be used to 
move a small number of fields.) 


Exit to SUBR90 


You must prepare the record area before doing an output 
operation using SUBRQ1. Therefore, you must move fields 
into this area of storage before requesting the |/O opera- 
tion. For input operations, you are presented with a mass 
of data from which you must extract specific fields. When 
you use SPECIAL file processing, the input and output 
specifications provide this capability. However, in RPG II 
Calculations there is no facility for selecting fields from 
various sections of another data field. Thus, SUBR9QO is 
provided to serve this purpose. 


Figure 6-14 illustrates the coding required to link to SUBR90. 
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Figure 6-14. Coding Required to Use SUBR9O 


The first four RLABL’s following an EXIT to SUBR90 
provide information to SUBR9Q0 about the fields to be 
moved, 


A | The first RLABL is an indicator. If you ‘‘set on” 
this indicator prior to exiting to SUBR9O, the sub- 
routine moves the data from the fields specified in 


subsequent RLABL’s to the record area. If the B 


indicator is off when control is given to. the routine, 
data is moved from the record area to the fields 
specified. 


B | The second RLABL is a field which must contain E | 
either the total length of data to be moved, if 
moving data to the output area, or the total length 
of the record area, if moving data from the input 
area to fields. The total length of all the fields which 
are to be moved from or to the record area must be 
less than or equal to the value contained in the field 
named by this RLABL. 
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E 
Rein oR) IR »4)) | -| where to be the 
‘| length you desire. 
FILID 
re THIF 
FILID “| These field names are used as ||| | |. 
| .| examples; they are not required | | | | 


“Resulting 






Result Field indicators 
[Minus] Zero | Conmnents 
Name Length 7 


<2] i= 2] 
Lookup(Factor 2)is' 
High } Low | Equal 
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The third RLABL must name the data area used with. 
SUBRQ1. If the data area is larger than 256, an alpha 
array may be defined which is at least as large as the 
data area needed. In this case, the third RLABL 
passed to SUBR9O should be the first element of the 
array (indexed by the integer 1). 


The fourth RLABL must name a field which contains 
the number of fields to be moved to or from the data 
area. It also defines the number of RLABL’s which 
follow the fourth RLABL. 


The fifth and succeeding RLABL’s name the fields 
which are to be moved to or from the data area. 
These names may refer to fields, or an array indexed 
by a constant. The RLABL’s may not name an array 
without an index. Fields are moved into the data area 
in the order you specify them as RLABL’s; therefore, 
the fifth RLABL must identify a six-position terminal 
name field as the first field in the record area. There 
must be a character-for-character correspondence 
between the “from” and “to” fields; if blanks are to 
occur in the data area, fields containing blanks must 
be provided in the list of RLABL’s. 


Alphameric and Numeric Fields 


Alphameric and numeric fields are properly left-justified 

or right-justified by your RPG || program prior to being 
moved to the record area by SUBR90 (SUBR90 treats 

all fields as alphameric fields). On input operations, how- 
ever, the terminal operator must know whether he should 
enter data into a field left-justified (alphameric) or right- 
justified( numeric). These instructions may have been 
given previously to the terminal operator by means of a 
published procedure, preprinted typewriter form, or a 
display format (3270). If not, your program should put 
out a format to the terminal before any data is requested 
from the terminal to indicate to the operator where the 
data should appear in the record and how fields should be 
justified. For batch terminals, such as other central process- 
ing units, this step is unnecessary, since the communicating 
programs will be written to expect data in a certain format. 


Editing with SUBR90 


The standarcl RPG HI editing facilities available with the 
SPECIAL file interface to the CCP are not available with 
the EXIT/RLABL interface. Therefore, SPECIAL is 
recommended if edited fields are to be used. 


If editing must be performed when using SUBR90, either 
you must provide coding in your program to insert and 
remove editing characters or edit characters must be shown 
on preprinted fields at the terminal. For 3270 terminals, edit 
characters may be placed on the display as part of a display 
format. 


If the 3270 Display Format Facility is used, negative 
integer numeric fields (no decimal positions) are automati- 
cally converted so that the minus sign is printed to the right 
of the value in the field. Likewise, on input operation, the 
field is automatically converted by 3270 DFF to its internal 
negative form (D zone in the right-most position of the 
field -- see negative numbers in the RPG I! Reference 
Manual). 


Exit to SUBR87 and SUBR88 


SUBR87, an entry in SUBR88, is used to issue Chain Task 
Request operations from RPG II programs. SUBR88 is 
used to accept both program-request and chain-task data 
by RPG II programs. 


Unlike SUBR91, SUBR87 and SUBR88 do not require a 
parameter list; instead, you specify two RLABLs. The 
first RLABL specifies an output data length (for SUBR87) 
or an input data length (for SUBR88). The second RLABL 
specifies the record area that consists of a name field and 
a data area. The name field is six characters long. When 
using SUBR87, you must place the name of the program 
to be requested, left-justified and padded with blanks if 
not six characters long, in the name field. When using 
SUBR88 to accept task chaining data, SUBR88 places the 
name of the program that requested the task chain into 
the name field before returning control to the chained 
routine. The data field is used to pass data between 
programs. 


SUBR87 and SUBR88 set on indicator 91 if the accept 
operation resulted in a negative return code, and indicator 
92 if the operation resulted in a positive return code other 
than a 14 return code. The 14 return code indicates a 
successful accept operation of the chain request data. 


Figuré 6-15 shows an example program (PGM1) that uses 
SUBR87 to issue a chain request and an example program 
(PGM2) that uses SUBR88 to accept the task chain data. 
SUBRQ3 is used in both examples to bypass the record 
selection in the RPG II program cycle. Input and output 
occurs in calculations using SUBR87 and SUBR88. 
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If the Overlay Linkage Editor is entered directly frorn the 
RPG I! Compiler, and the program being compiled con- 
tains exits to SUBR87 but does not contain at least one 
exit to SUBR88, a halt (EO ‘P 25) will occur. This halt 
occurs because the linkage editor cannot resolve internal 
entry points of subroutines (see the /BM System/3 Overlay 
Linkage Editor Reference Manual, GC21-7561 for addi- 
tional information on the linkage editor). One method to 
avoid this halt is to code a dummy exit to SUBR88 as 


shown in the following example: 


EXIT SUBR87 

RLABL LEN 

RLABL DAREA 

GOTO BYPASS 

EXIT SUBR88 
BYPASS TAG 


Another method to avoid this halt is to compile the pro- 
gram andi place the non-link-edited program in a library 
(see object output in the /BM System/3 RPG I! Reference 
Manual, 8C21-7504, for additional information). Then 
call the linkage editor (SOLINK). The OCL for this pro- 
cedure is shown in the following example: 


// CALL RPG,R1 

// COMPILE SOURCE-rpgchn,OBJECT-nn,UNIT-nn 
// RUN 
// CALL 
// RUN 
HANCLUDE NAME-rpgchn,UNIT-nn 
//INCLUDE NAME-SUBR88,UNIT-nn 
HINCLUDE NAME-SUBR93,UNIT-nn 
// END 


OLINK,R1 


Notes: 

1. Rpgctin is the name of the program containing the task 
chain exit. 

2. The FILE statements are handled by default in the 
example. 

3. As with SUBR91, SUBR93 must be included as a 
dummy input file when using SUBR88. 
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Setting the Parameters for EXIT/RLABL Operations 


All parameters for CCP operations are placed in the para- 
meter array. The program name or the symbolic terminal 
name is always placed in the record area (see EX/T to 
SUBR91). 


Operation Code 


In setting the operation code, you can avoid having an 
invalid operation/modifier combination by always moving 
both parts of the operation code into the second array 
element. The valid operation and modifier codes are given 
in CCP Operation Codes, earlier in this chapter. 


Output Length 


For EXIT/RLABL output operations, place the length of 
the output data in the third array element. The output 
length includes device control characters which you are 
inserting into the data in your program (see index entry 
Device Control Characters). The output length should 
not include the six characters for the program name or 
the symbolic terminal name. 


The maximum output length you can specify is 4090. See 
RPG I! Programming Considerations, later in this chapter, 
for information about using the third array element with 
the Acquire Terminal operation. 


Maximum Input Length 


The maximum input length in the fourth array element for 
an EXIT/RLABL operation must not include the six 
characters for the program name or the symbolic terminal 
name, but must include the length of any device control 
characters you are handling in your program. You must 
enter a maximum input length for the following operations: 


@ Get 

@ Invite Input 

® Put-Then-Get 

®@ Get Attributes 

If you also specify a maximum input length for the Accept 
Input operation, it will override the length given for the 


Invite Input operation. For the Get Attributes operation, 
set the value of the fourth array element to 21. 
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Figure 6-15 (Part 1 of 2). Coding for SUBR87 and SUBR88 
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PGM2 
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Figure 6-15 (Part 2 of 2). Coding for SUBR87 and SUBR88 
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Examining Returned Information 
After you have issued a CCP operation using EXIT/RLABL, 
you should examine information returned to your program 


by the CCP: 


@ Return Code (Note: Indicators 91 and 92 are not 
reserved or used with SUBR9Q1.) 


@ Effective input length (if an input operation was 
performed) 


@ The program name or the symbolic terminal name (if it 


was set by the CCP, such as for an Accept Input opera- 
tion or a Put issued with a blank terminal name) 


Testing the Return Code 


After an EX!IT/RLABL operation, the CCP places the 


return cade in positions 5-6 of first parameter array element. 


Figure 6-16 shows an example of testing the return code 
for plus, minus, or zero by means of a compare operation 
and resulting indicators. In this example, a subroutine that 
checks for specific return codes is executed when a positive 
or negative return code is encountered after a Stop Invite 
Input operation. Before checking the return code after an 
EXIT/RLABL operation, you must move the return code 
from the first array element to a 2-position numeric field. 


Note: Notice the use of a MOVEL instruction to move the 
terminal name from the field TNAME to the first six 
positions of the record area, INREC. This technique is 
useful when the record area consists of the symbolic 
terminal name and a single field (in this case assume the 
input record is a single 10-character field). 


Examining the Effective Input Length 


After operations that return input data to your program, 
you may need to know the actual length of input data 
returned to your program, that is, the effective input 
length. This value does not include the six characters for 
the program name or the symbolic terminal name and 
does not include the length of truncated data when a 
terminal sends more data than you specified in your maxi- 
mum input length for the operation. Special considerations 
are involved when you use the 3270 Display Format 
Facility {DFF) input operations; see 3270 Display Opera- 
tions. 


In order to use the effective input length, you must first 
move the contents of the third array element to a numeric 
field. 


Symbolic Terminal Name 


On EX!IT/RLABL operations for which the CCP returns a 
terminal name (see index entry Operations), you may need 
to examine or otherwise use the terminal name (for example, 
to associate the input data with data previously received 
from the same terminal). The CCP places the returned 
symbolic terminal name in the first six positions of the 
record area. 


See Programming Examples, Example 2, \ater in this chapter, 
for examples of saving and examining terminal names in an 
MRT program. 


3270 DISPLAY FORMAT FACILITY 


You can use the 3270 Display Format Facility (DFF) of 

the CCP to aid you in formatting and using the 3270 
terminal. Chapter 8. 3270 Display Format Facility describes 
the programming requirements that are unique to using the 
DFF, including the unique DFF operations, additional 
information that must be placed in the record area for 
certain operations, field types that are unique to the 3270, 
and other information. 


You can compare the programming necessary to use the 3270 
without DFF to programming with the DFF by comparing 
Example 1 under Programming Examples, \ater in this 
chapter, ta the example in Chapter 8. 


RPG Il PROGRAMMING CONSIDERATIONS 


This section contains some reminders, suggestions, and 
restrictions pertaining to writing RPG I! programs to 
run under the CCP. 


Data Mode Escape and Release Terminal Operation 


If data mode escape is allowed in your CCP system (speci- 
fied by the ESCAPE keyword in the $EFAC generation 
statement—see CCP System Reference Manual) you must 
include coding in your program to test for the 08 return 
code (terminal has entered data mode escape and released 
itself from your program). When the CCP returns a 08 re- 
turn code after an input operation (Accept Input, Get, or 
Stop Invite Input), a count of outstanding Invite Input 
operations is returned in the third element of the parameter 
array (effective input length). In an MRT program, you 
should check this count to determine how many terminals 
are still attached to your program. If you do not check this 
count, you might do an Accept Input operation without 
having an outstanding Invite Input, causing the CCP to 
cancel your program (unless it is a never-ending program— 
see index entry). 
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Figure 6-16. Checking the Return Code After an EXIT/RLABL Operation 


Following a Release Terminal operation in an MRT program, 
the CCP also returns a count of outstanding Invite Input 
operations in the third array element. You should check 
this count to avoid doing an Accept Input operation without 
an outstanding Invite Input. (The Release Terminal 
operation always returns a 00 return code.) 


Using Both SPECIAL and EXIT/RLABL 


You should be aware that when you use both SPECIAL 
and EXIT/RLABL for CCP operations you are adding 
additional code to your program, since at least two sub- 
routines must be included. Therefore, if you are concerned 
about the size of your program, you can reduce its size by 
using only one of these methods of performing CCP 
operations. 
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You must be sure to specify the correct communications 

service subroutines for SPECIAL and EXIT/RLABL. For 
example, if you mistakenly use SUBR91 with SPECIAL, 

the results are unpredictable. 


Multiple Output Lines 


When sending multiple H, D, or T output lines in a single 
program cycle or when sending multiple output lines with 

a single EXCPT operation, you should condition the output 
lines with indicator N97 so that you can react to output 
errors when they occur. However, even if you use this 
technique, it is difficult to determine which output lines 
were or were not successfully sent in this case. 


End of File with SUBR92 


Remember, when using SPECIAL files with SUBR92 you 
will never get end of file on a SPECIAL file unless you 
issue the Force End of File operation to the file (see CCP 
operation codes, earlier in this chapter). Therefore, the 
end of file indicator in positions 58-59 of the Calculation 
specification for the READ operation is meaningless unless 
Force End of File is used. 


Host/Subhost Communications 


Considerations for communicating with host and subhost 
systems via BSCA are given in Appendix A. 


Communicating With the Console 


You can communicate with the system operator console 
only by means of Put and Put-Then-Get operations. The 
symbolic terminal name for the console is CONSOL. 


You cannot issue an Acquire Terminal operation to the 
console (there is no need, since any program can communi- 
cate with the console at any time). 


You cannot communicate with the system operator console 
by specifying CONSOLE (Model 10 Disk System and Model 
12) or CRT77 (Model 15) as the device in columns 40-46 
of File Description Specifications. 


Master Inciex 


CCP builds an in-storage index based on either the 
MSTRINDX or MIXSIZE keyword of the DISKFILE 
assignment statement (see CCP System Reference Manual). 
Specify a master index for disk files in the application pro- 
gram as follows: 


@ Ona Model 10 or 12, specify at least one master index 
entry (key length plus 2) in the application program to 
“make use of a master track index. This improves per- 
formance for large index files. 


@ Ona Model 15, a master index entry is not required in 
the application program to make use of the master track 
index. 


Disk File Usage 


You should be aware of how other programs running under 
the CCP are using disk files that you also use in your pro- 
gram, especially if records are being added to the files. 

See index entry disk file considerations for detailed in- 
formation. 


Specific Restrictions 


® Do not use multivolume files (columns 68-69 of the 
File Description Specifications must be blank). 


® Do not use magnetic tape files. 
@ Do not use look-ahead fields. 


@ Do not describe a SPECIAL file for CCP operations as 
a table file. 


® Do not use the RPG I! inquiry feature. 


@ (Model 10 and Model 12 CCP) Do not use RPG II halt 
indicators. If programs running under the CCP issue 
halts, they will be cancelled. 


PROGRAMMING EXAMPLES 


The following programming examples are explained in this 
section. 


Example 7—an RPG II program that supports a single 
requesting 3270 without using the Display Format Facility. 


Example 2—an RPG II program that supports multiple 
requesting terminals. 


See Chapter 8 for examples of RPG I! programs that use 
the 3270 Display Format Facility. 


Before attempting to use these examples, you should read 
and understand the description of the RPG II CCP 
interface in this. chapter. 


Example 1 


Figures 6-17, 6-18, and 6-19 show the flowcharts, messages, 
and listing for a single requesting terminal (SRT) RPG II 
program (see index entry SRT program). This program 
transmits two messages to a 3270 Model 1 Display System 
(480 character screen). The first message from the program 
requests the terminal operator to enter a room number. The 
program uses the room number entered by the terminal 
operator as the relative record number to access a disk file 
whose records contain guest and rate information about 

the room. This information is then formatted and dis- 
played as the second message transmitted to the 3270 
terminal. The program then goes to end of job. Figure 6-17 
also shows how these messages appear on the 3270 terminal. 
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Because this program is a single requesting terminal (SRT) 
program (see index entry), it can receive data from and 
transmit cata to only one 3270 terminal. However, 
multiple copies of this program could be in main storage 

at the same time (if the system has sufficient main storage), 
each communicating with a different 3270 Display System. 
(If multiple copies are in core at the same time, the disk 
file must be specified as sharable during the Assignment 
stage—see index entry disk file sharing.) 


Formatting the Messages for the 3270 Display 


Because this sample program does not use the Display 
Format Facility, this sample program must provide for- 
matting contro! characters for the display screen in the 
data portion of the record area and transmit them as part 
of the messages to be displayed. Figure 6-19 shows the 
messages and the 3270 control commands and orders as 
they are transmitted to the 3270. See /BM 3270 Informa- 
tion Display System Component Description, GA27-3004, 
for a description of 3270 system components, concepts, 
control commands, and orders. 


The printable format characters are set by defining them 
as part of the message in the RPG I! Output Specifications 
definition. 


The unprintable format characters (hexadecimal values that 
have no corresponding printable character in.96-colurmn 

card code) are in a pre-execution time array (ORDERS) 

that was loaded by a previous RPG I! program (see comments 
in File Description Specifications), Elements of the 
ORDERS array are then used in appropriate positions in 

the output messages. 


Notes Concerning this Sample Program 


@ Message Mode was defined during CCP assignment for 
the 3270 terminal used by this program. (See 
TERMATTR statement in CCP System Reference 
Manual.) This eliminates the need to do repetitive 
input operations until EOT is received. 


® To run this program using a terminal other than the 3270, 
you must remove all coding dependent on the 3270, 
This includes all screen formatting specifications and 
3270 screen contral characters within the data. 


®@ This program will not accept data with the prograrn 
request. 
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® This program specifies a Put with Invite Input operation 
using a blank terminal name as the first operation (1P 
output time in the RPG II program cycle). In an SRT 
program such as this, the blank terminal name refers 
to the current requester of the program. The name of 
the requester is received in the TNAME field of the 
input record area after the Accept Input operation. 


®@ To keep this sample program simple, return code checking 
is kept to a minimum. You should do more return code 
checking in your application programs. For example, 
when you issue Accept !nput you should check for the 
Shutdown Requested return code (04). Also, if data 
mode escape is allowed in the CCP system, programs 
should check for return code 08. It is recommended that 
each installation design its own return code checking 
and/or console communication routines so that a satis- 
factory standard is established for the installation that 
can be used in all application programs. 


@ This program does not check the length of the input 
data because the terminal operator is requested to 
enter a three-digit room number. However, you may 
want to check the input data length in your application 
programs. 


@ Since there are only two different screen formats used 
by this program, they are both contained within the 
program.. For more complete applications, you might 
store the screen formats on disk and read them when 
they are needed by your program. 


® You could also use the Get Attributes operation in this 
program. For example, if you do not know whether 
the 3270 Model 1 or the 3270 Model 2 will request the 
program, you can issue a Get Attributes operation to 
find out which type of terminal requested the program. 


@ If this program were coded and specified as a multiple 
requesting terminal (MRT) program with a MRTMAX=1 
keyword on the PROGRAM assignment statement (see 
CCP System Reference Manual), multiple copies of the 
program would not be allowed in main storage at the 
same time. As the program is written, multiple copies 
could be in main storage at the same time and the disk 
file must be specified as sharable (FILES keyword of 
PROGRAM assignment statement). 


START 


ENTER ROOM # _ 


Issue Put with Invite Input operation 
to send the initial message to the 
requesting terminal. 





Accept Input (Room #) from 


requesting terminal. ENTER ROOM #009 






Return Code No 


= 0? 





Yes 












Read disk record. (Room # is 
relative record number.) 


ENTER ROOM #009 
ROOM #- 009 

RATE - $18.50 
NAME - JOHN DOE 
ADDR - 114 5TH AVE SW 
Issue a Put-No-Wait (message) to ADDR - STURGIS, MINN. 55101 
display room #, rate, name, and 
address. 


END OF JOB 


Figure 6-17. Program Logic of Example 1 (RPG I! SRT Program) 
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First Message 








18 19 20 21.27 92 24 2 28 27 2H 29 31 7 334 


bx, Ixlx 





























— Start Field 








SF 

ATT — Attribute Character WCC — Write Control Character 

1C — Insert Cursor SBA — Set Buffer Address 

x — Data Character BA -— Buffer Address of first character 
EC —Escape Character position in the field 





Figure 6-18. Message Formats for Example 1 (RPG II SRT Program) 
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01010H R 4 


In this example, the same array is 
used for the input and output 
SPECIAL files since it is convenient 
and saves space in the program. 


——— 


The parameter array is a compile 
time array in this example, so the 
array contents are set when 1P out- 
put is performed (see the first 
message). 


At input time in the program cycle 


Invite Input has been issued at 1P 
output time. 


BAD AID,RTN COD The program expects a room number 
between 1 and 10. If a different 
number is entered, the program does 

not attempt to access the GUEST 

file for rate, name, and address. 

Only the room number is printed on 

the T output line. If the operator 

enters an incorrect room number 
such as 166, the room number is 

displayed as 100. 


A Put with invite Input operation 
with a blank terminal name issued at 
1P output time sends the initial 
message to the terminal and invites 
input from the terminal. The maxi- 
mum input length (25) for the Invite 
Input is in the parameter array. 


0001 0102 FTPIN rp 25 SPECIAL SUBRI2 
0002 0103 F KIARR 
0003 010% FTPOUT Go 138 138 SPECTAL SUBR92 
0004 0104 F KIARR 
0005 0106 FGUEST Ic 70 70R DISK 
0006 0108 FORDERS IT 4 4 EDISK 

0109 F* THIS FILE WAS LOADED BY A PREVIOUS RPS PROS SINCE IT CONTAINS HEX- 

O110° F*ADECIMAL DATA THAT MUST BE AVAILABLE AT 1P OUTPUT. THAT RPG 

O111 F*PROGRAM COULO HAVE CREATED THESE CHARS WITH THE SET BIT 

O1l2 F*INSTRUCTION OR FILE TRANSLATION. 
0007 0201 € TARR 0050005 06 INOQUT CCP ARRAY 
0008 0203 E ORDERS ORDR‘ 4 4 01 3270 ORDERS 

0204 E** THE FOLLOWING ORDERS (1 CHARACTER EACH) ARE CONTAINED IN THE 

0205 E** ORDR ARRAY - OROR:1 -ESCAPE CHAR 

0206 Ex* ORDR»2 -SET BUFFER ADDRESS 

0207 Ex* ORDR»3 -START FIELD 

0208 Ex* OROR A NSER CU OR es 
0009 0301 ITPIN AA Ol 17 C! _an Accept Input is issued. The 
0010 O30101 5 BOEFL 
9011 030201 9 14 TNAME 
0012 030211 23 250R00M 
0013 030301 AB 02 

O30401** CATCH ALL FOR UNIDENTIFIED RECORD 
0014 0308 IGUEST BA 03 1 CG 
0015 0309 I 2 4 GROOM 
0016 0310 I 5 82GRATE 
ool? 0311 I 9 28 GNAME 
0018 0312 I 29 48 GADDRL 
0019 0313 I 49 68 GADOR2 
0020 0314 I BB 05 

0315 I** CATCH ALL , 

$0305 E*NOTE: POSITION 17 IS AN AID CHAR. A SINGLE QUOTE MEANS THE 

0306 I*ENTER KEY WAS KEYED. ANY OTHER AID CHARACTER OR NON-ZERO 

0307 I*RETURN CODE ON INPUT CAUSES THIS PROGRAM TO GO TO END OF JOB. 
0021 04010C 91 
0022 04011C0R 92 
0023 04012COR 02 SETON uR 
0024 0402 C LR GOTO END 
0025 0403 C 01RO0M COMP 1 LR ROOM # ENTERED 
0026 0405 C LR GOTO ENO 
0027 0406 C 01R00M COMP 10 LR 
0028 0408 C LR GOTO ENO 
0029 0409 C 01ROOM CHALNGUEST 
0030 04100C 05 SETON LR 
0031 0411 C 03 SETON LRO4 
0032 041211C 03 SETOF 9291 
0033 0412 C END TAG 

OSOLOO*FORMAT THE SCREEN FOR DATA ENTRY. 
0034 O50L1L0TPOUT H 1p 
0035 0502 0 14 ¢ ' 
0036 0503 0 4" §* 
0037 050310 8 "40! 
0038 0504 0 OROR»1 15 

0505 O* HEX*27" -— ESCAPE CHAR 
0039 0506 0 16 ¢5! 

O507 O* HEX'FS* = ERASE/WRITE 
0040 0508 0 17 *G! 

0509 O* HEX'C7* - WRITE CONTROL CHAR (SOUND ALARM,RESTORE KEYBOARD, 

0510 O* RESET MODIFIED DATA TAGS) 
0041 0511 0 GRDRy2 18 

0512 O* HEX'11° ~ SET BUFFER ADDRESS COMMAND 
0042 0513 0 2o*r ¢ 

0514 O* HEX'4040" ROWL COL1 3270 MOD 1 
0043 0515 0 32 ‘ENTER ROOM #* 
0044 0601 0 OROR,3 33 

0602 O*¥HEX*1D'-START OF FIELD 
0045 0603 0 34 "I? 

0604 O# HEX*C9"-UNPROTECTED ALPHAMERIC INTENSIFIED 
0046 0605 0 OROR +4 35 

0606 O* HEX'13"=INSERT CURSOR 
0047 0607 Q 38 * - 

0608 O# AREA FOR ROOM NUMBER 
0048 0609 0 OROR»3 39 
0049 0610 0 40 "O° 

0611 O* PROTECT REMAINDER OF SCREEN 
0050 0701 0 T LR 04 
0051 0702 0 4 ‘CF! 
0052 070210 8 "138° 
0053 0703 0 TNAME 14 
0054 0706 0 ORDR»1 15 
0055 0707 0 16 "1¢ 

O70710*WRITE ONLY 
0056 0708 0 17 'G* 
0057 0709 0 ORDR»2 18 
0058 20.' ¥! 


0710 O 


Figure 6-19 (Part 1 of 2). Example 1 — RPG !! SRT Program 
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O711 O* 3270 Ml ADDRESS ROW2 COL] 


0059 O712 0 29 "ROOM # ~ * 
0060 O712 0 GROOM 32 
O06L 0714 0 ORDRe2 33 
0062 0718 0 35 "AE? 
0716 O* 3270 M1 ADDRESS ROW3 COLL 
0063 0801 0 42 "RATE - ° 
0064 0802 0 GRATE 3 48 '$! 
0065 0803 0 ORORy»2 49 
0066 0804 0 51 "AB! 
0805 Q* 3270 Ml ADDRESS ROW4 CCL1 
0067 0806 0 58 ‘NAME - ¢ 
0068 0807 O GNAME 78 
0069 o808 0 CROR¢2 79 
0070 0809 0 61. * B=" 
0810 O* 3270 ML ADDRESS ROWS COL1 
oo71l 0811 0 88 "ACER - ' 
0072 0812 0 GADORI1 108 
0073 0813 0 ORORs2 109 
0074 0814 0 111 'CH® 
0815 O* 3270 M1 ADDRESS ROW6 COLL 
0075 O901 0 118 ‘ADDR - § 
0076 0902 0 GADDR2 138 
0903 Ox* END OF PROG ** 
kx 
0 25 


INDICATORS USED 
LR LP Ol O2 03 04 95 91 92 


3G 314 UNREFERENCED TABLE/ARRAY NAMES 


STMT# NAME 
0007 TARR 
EXECUTION TIME TABLES AND ARRAYS 

STMT# YABLE/ DEC ENTRY NUMBER OF OTT T/A 
DEFINED ARRAY POS LENGTH ENTRIES DISP DISP 

0008 ORDR 001 00004 0100 0000 
3G 314 UNREFERENCED FIELD NAMES 
STMT# NAME 

0010 EFI. 


FIELD NAMES USED 
STMT# NAME DEC LGTH DISP 


0011 TNAME 006 0009 
0012 RODM 0 003 0046 
0015 GRODOM 003 000Cc 
0016 GRATE 2 004 O04F 
0017 GNAME 020 0020 
0018 GADDR1 020 0034 
0019 GADDR2 020 0048 


LABELS USED 
STMT# NAME TYPE 


0033 END TAG 
COMPILE TIME TABLES ANO ARRAYS 
STMT# TABLE/ DEC ENTRY NUMBER OF DTT T/A 
DEFINED ARRAY POS LENGTH ENTRIES DISP OISP 
0007 TARR 006 0005 0000 000D 
TARR 


D 25 
END OF TABLE/ARRAY - LAST ENTRY WAS BLANK 


ERROR NUMBER STATEMENT NUMBER 


RG O97 0014 
RG 097 0020 
RG 558 0029 
ERROR SEVERITY TEXT 
RG «4097 W NO FIELOS DESCRIBED FOR THIS GR PREVIOUS RECORD. 
2G 314 Ww FIELD, TABLE OR ARRAY NAME DEFINED BUT NEVER USED. 
2G 392 W LAST ENTRY IN ONE OR MORE COMPILE TIME TABLE/ARRAYS WAS BLANKs 
wG 558 Ww INVALID USE OFy OR MISSING, RESULTING INDICATORS WITH THIS OP CODE. 


INVALID RESULTING INDICATORS BLANK. 
Figure 6-19 (Part 2 of 2). Example 1 — RPG Il SRT Program 
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001110 


ASSUME 


Example 2 


Figures 6-20, 6-21 and 6-22 show the flowchart, input/ 
output messages, and listing for a sample RPG I! multiple 
requesting terminal (MRT) program designed to run under 
the CCP (see index entry MAT program). This program 
handles up to four MLTA requesting terminals. The terminal 
operator enters a seven-digit number preceded by a +, -, or 
N. The CCP transmits this signed number to the RPG Ii 
program. The RPG II program: 


Adds the number to the value in the accumulator 
associated with the terminal that transmitted the data 
if the first position is +. 


Subtracts the number from the accumulator if the first 
position is ~. 


Releases the terminal if the first position is N. 


lf a value was either added or subtracted, the new value 
accumulated for the terminal is inserted into the message 
CURRENT VAL = sxxxxxxxxxx ENTER DATA and the 
message is sent to the terminal. 


This sample program also checks for several error con- 
ditions and transmits the appropriate error message to the 
terminal requesting the operation. 


This sample program is not designed to show the most 
effective way of performing operations. Instead, it shows a 
variety of ways to do things. It uses a variety of operation 
codes that show how data can be associated with a terminal 
by defining a save area for the terminal names and accumu- 
lated data. It frequently checks return codes; but you can 
do even more return code checking if you wish. Data 
entered by the terminal operator must be fixed length. To 
allow variable length input fields, you could include a 
subroutine in your. program to check the effective input 
length returned in the parameter list and align the data 
correctly. This program communicates with the console 

in addition to the requesting terminals. 
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l—e 2 


1. Check input 











1. Set up parameter length = 8 
list for Accept 2, Check valid 
Input operator 


2. Accept Input 3. Check valid data 


C1 c4 No 1. Set up Put-No- 
3A3 Valid input Wait (message) 
2. Initiate Put 
Return code 


checker routine Yes 










D1 pe Find proper 
Shutdown Yes CSA accumulator 
request hutdo 
No 
. N Add b 
° 2 or subtract 
Terminal No Terminal oe nee to neues 
antes canceled SEs accumulator 
Yes S Yes 
F1 F2 


Terminal Yes Set canceled . Move ‘'-” to out- 
canceled switch put area 


. Make unit position 


No er printable 












G1 . Set up Put, Wait 
Negative Yes message 
return code . Put message 
<<  e 
H2 
ee H4 - 
Positive return Yes 1, Set up Put-No- Return code No 
code (#0) Wait (message) 


=0 


2. Initiate Put () (204 
No 
J (s+) 1. Set up Invite Input 


2. Invite input 
Operator = N ee 


- By 


Figure 6-20 (Part 1 of 3). Program Logic of Example 2 (RPG It MRT Program) 
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Retry = 
try again 


Yes Terminal 
canceled 


Gi 
1. Set up Release 
Terminal op. 
2. Release terminal 


H2 


1. Clear terminal 


name entry in 
attached list 
2. Clear accumulator 
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- {input TP Error 


-2F4 


Console Routine 


Retry = try 
again 


. Set up Put-No- 
Wait (message) 
. Issue Put 







Console Routine 


F4 


ENTER 


G4 


1. Set up Put-Then 
Get to console 

2. Issue Put-Then- 

Get 









H4 







Set on release 
terminal 
indicator 






Reply = TA 
(try again) 


J4 


RETURN 


RPG il 639 


Shutdown Routine 


Al 
( ENTER 






Check entry N in 
attached list 


D1 
Entry blank 
E1 


1. Set up Stop Invite 
2, Stop Invite 






F1 


Return code 
checker routine 
G1 
Terminal 
canceled 


H1 












. Set up Put, No 
Wait message 
2, Issue shutdown 
message 








Ki 
| Add 74 toh 


Return Code Checker Routine 


A3 






ENTER 


B3 







>0 
Set on O 


indicator 






Return code 








Set on 0 
indicator 
(TP error) 








D3 







Set on invalid 


Return code eg 
data indicator 





Set on shutdown 
indicator 


F3 
<8 =8 
Return code 


>8 









Set on terminal 
canceled 
indicator 






G3 
Set on Stop Invite 
successful 
indicator 






Return code 
=10 





H4 


RETURN 
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Input Data Entered by Terminal Operator 


1234 5 6[ 7/8 9 10 1 12 








A fixed length numeric field where S is at a+, -, or N and 
X is a numeric digit. All eight positions must be entered, 
except.when N is entered in the first position. 


























Data Entered by System Operator on 5471 Printer/Keyboard (Models 10 and 12) or CRT/Keyboard (Model 163) 


Cee In response to the messages INPUT TP ERROR TNAME-cccccc and 


OUTPUT TP ERROR TNAME-cccccc to the console, the system 
operator replies TA if he wants to Try Again. Any other reply (cc) 
causes the terminal to be released. 








Output to the Console 











These messages are transmitted 
to the console (cccccc = terminal 
name). 






































Transmitted with value 
in accumulator associated 
with the terminal. 
































Issued if data is invalid 



































Issued if system operator replies TA 
(Negative return code on Accept Input) 























Issued for negative return code on 
Stop Invite Input 





















































Issued for positive return code other 
than 10 on Stop Invite Input 






































Issued for return code of 0 on 
Stop Invite Input 


Issued for return code of 10 on 
Stop Invite Input 


Figure 6-21. Input and Output Message Formats for Example 2 (RPG I! MRT Program) 
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01010H R 4 MRRPGL 
0001 O2010FDUMMY IP 1 L SPECIAL SUBR93 MRRPG1 
0002 O2020FTPCONSIOCD 52 52 SPECIAL SUBR92 MRRPG1 
0003 02030F KTPRY MRRPGL 
0004 03010E TPRY 5 6 CCP PARM LIST MRRPG1 
0005 03020E ATRY 4 6 ATTACHD TERM LISTMRRPG] 
0006 03030E ACMY 4 100 ACCUMULATOR LIST MRRPG1 
0007 O4010I10UMMY AA O1 MRRPGL 

040201*% DUMMY SPEC FOR PRIMARY FILE (RPG REQUIRES A PRIMARY FILE) MRRPGL 
0008 O4030I1TPCONSIOBB 02 MRRPGL 
0009 040401 1 20RETCOO MRRPG1 
0010 040501 5 BOEFFL MRRPGL 
OOl1 040601 9 14 TNAME MRRPG1 
0012 040701 15 15 OPRATR MRRPG1 
0013 04080! 16 220TPIPT MRRPGL 
0014 040901 15 17 CONSIP MRRPGL 

O5010C*%** CHECK THE 3RD ELEMENT OF THE PARAMETER ARRY TO DETERMINE IF MRRPG1 

05020C** IF ANY MORE TERMINALS TO BE SERVICED. IF NOT GO TO EQJe MRRPGL 
0015 05030C ACPIPT TAG MRRPG1 
0016 05040C o9 MRRPG1 
0017 05050COR L3TPRY,3 COMP * Qooo' LR NO MOR IF O MRRPG1 
0018 05060C LR GOTO END GO TO EJ MRRPG1L 
0019 OS5070C O1N SUB ON N 10 CLEAR INDEX MRRPG1 
0020 05080C ol MOVE * Df TPRY¥92 ACP IPT OP CODMRRPG1 
0021 05090C ol MOVE ‘22! TPRY V4 MAX XPECT LEN MRRPGL 


05 LOO CR io RO IR OO OO i ioloidoi toi iatoiukiaiokiok # aokiuk a tom iok ick ck MRRP G] 


05110C* MRRPGL 
05120C* ACCEPT INPUT MRRPG1 
05130C* MRRPGL 


051400 GK iO i a ao moi igor aloo ici ik gaiiciaiotak dtog toc MRRP G1 


0022 05150C OL READ TPCONSIO ACCEPT INPUT MRRPG1 
05 160 Cae e IO IO RIO a tol i toi ai io doi i tok oak dea ak dak aka dca ak tok MR RPG 1 
05170C* MRRPGL 
05180C* GO TO RETURN CODE CHECKER ROUTINE MRRPG1L 
05190C* MRRPGIL 
052000 ee aa RI RIO OOO OO IO OO I ii i tok doioak a icitcdck dick ek MRRP G1 

0023 06010C 02 EXSR RETCHK CHECK RIN CODE MRRPG1 
06 02 00 #3 RO II IOC IO lop iI iO a iam i io icici dakar aba tok MR RPG 1 
06030C* MRRPG1 
06040C* IF SHUTDOWN REQUEST RETCOD = 04,IND ON IS 06 MRRPG1 
06050C* MRRPGL 
060600 #38 OO IO a i ii iii tok iia ik a MR RP G1 

0024 06070C 06 GOTO SHTDWN SHUTDOWN CODE MRRPG1 
06 08 00 20 A oi io gio iO too io iio iui io ioioliciao iii iio ioinickacd doi ack tra MRRP G1 
06090C* MRRPG1 
06100C* ROUTINE TO DETERMINE IF TNAME IS AN ATTACHED TEMINAL MRRPGL 
06110C* IF ATTACHED IND 12 IS ONeIF NOT IND 13 IS ON MRRPG1 
06120C* MRRPG) 
06 1300 a ao oR aa aia GR RO nooo iE a Gg aOR RoR za aGR IRR ERIK MR RPG] 

0025 06140C LUP1 TAG MRRPG1 

0026 06150C 01 N ADD 1 N ADD TO INDEX MRRPG1] 

0027 06160C 01 ATRYaN COMP TNAME 12NAME FOUND MRRPG1 

0028 06170C Ol 12 GOTO GdQl MRRPGI 

0029 06180C 01 N COMP 4 13NAME NOT IN LSTMRRPGL 

0030 06190C O1N13 GOTO LUPL KEEP LOOKING MRRPG1 


062006 43 Ra oR i i doi iio kk dak io io io a ioicicialeg ea itor 40k MR RPG 2 


0701L0C* MRRPGL 
07020C* TERMINAL NOT ATTACHED AND CANCELED MRRPGL 
07030C* MRRPGL 


070400 AO OI IO OIG SIR a CG GOI IO kak toiaitai a tatek ick dk tok aK MRRP GL 


0031 o7050C 09 13 GOTO ACPIPT TERM CANCELLED MRRPG1 
07.0600 38 Oo ai OR a i i i tot fob i i et a ie doi i i MRRP G1 


OT070C* MRRPG1L 
07080C* IF TERMINAL NOT ATTACHED AND NOT CANCELED MRRPG1 
o7090C* ADD TERMINAL TO ATTACHED LIST MRRPG1 
07100C* MRRPG1 


07.20 Ca OR OO IG I IO IGOR IO I Itoi i a tl iaiaick dali ieioiik ido tee tokak MRRP G1 
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0032 07120C 13 N SUB ON N CLEAR INDEX MRRPG1 


0033 07130C Lup2 TAG MRRPG1 
0034 O7140C 13 N ADD 1 N ADD TO INDEX MRRPG1 
0035 O7150C 13 ATRYN COMP ¢ ' 14THIS NTRY AVAILMRRPGL 
0036 07160C 13N14 GOTO Lup2 NO TRY AGAIN MRRPG1 
0037 O7170C 13 14 MOVE TNAME ATRY)N YES ENTER NAME MRRPG1L 
0038 oO7180C 13 GOTO GO2 MRRPGL 
OT1LIOC FRR REE KE iO I oa io toi ai iio dali dak icici gakiokM RR PG 1 
07200C* MRRPGL 
08010C* IF TERMINAL WAS IN THE ATTACHED LIST AND RETURN CODE MRRPG1 
08020C* IS CANCEL,GO TO RELEASE TERMINAL ROUTIN MRRPGL 
08030C* MRRPGL 
O8040C #8 RR Ke Re ok ae RO IG III I I OO IO iO a ici ikea MRRP G1 
0039 08050C Gol TAG MRRPG1 
0040 o8060c. 12 09 GOTO RELEAS CLEAR TERM MRRPGL 
O8 0700 Oe tok ko iO igi co aC aoc ici loi igi aia doiiok gag gai aigioiaka ack MR RPG] 
08080C* MRRPGL 
08090C* IF NEGATIVE RETURN CODE-IND ON 1S 03,60 TO MRRPG1 
08100C* INPUT TP ERROR ROUTINE MRRPGL 
08110C* MRRPG1 
081200 #0 kk Ro iO i OC IO icici iio oii tok ici i dail io iotoaictokMeR RPG 1 
0041 08130C Go2 TAG MRRPG1 
0042 08140C 03 GOTO IPTER NEG RET CODE MRRPGL 
081500 % 3 Ok i ROO a mod Goi a iaictol oii dokaiaioiiotok iakaiat ick MR RPG 1 
08160C* MRRPGL 
08170C% IF POSITIVE RETURN CODE(GREATER THAN ZERO) BUT MRRPGL 
08180C* NOT EQUAL TO 10 GO TO INVALID DATA ROUTINE MRRPG1 
08190C* MRRPGL 
08 200C * * 4k ROR RIG ICI CC IOI a iio ok ia kok ok kok doko MRRP GI 
0043 09010C 07 GOTO INVDAT INV DATA ROUTINMRRPG1 
090200 3% ek tk III I II IG IO OI HORII i ko mak kik iki aokM RRP GL 
09030C* ' MRRPGL 
09040C* IF RETURN CODE=0,INO 04 IS ON AND IF MRRPGL 
09050C* OPERATOR=NyGO TO RELAEASE TERMINAL ROUTINE MRRPGL 
09060C* MRRPG1 
090700 %* RO Ro a Cato i ia Ri A Ci oka kick dota MRR PGI 
0044 09080C 04 OPRATR COMP *NE 13ANY MORE DATA MRRPG1 
0045 09090C 04 13 GOTO RELEAS NO, RELEASE MRRPG1 
09100 0 3C a ROR Oo oi ioc Rito gi a aK MRRPG] 
O9110C* 1 CHECK INPUT LENGTH = 8yIF NOT 8 TURN IND 07 ON MRRPG1 
09120C* 2 CHECK VALID DPERATOR »IF OPERATOR IS + TURN IND MRRPGL 
09130C* 14 ON, IF OPERATOR IS = TURN ON IND 15,1F OPERATOR MRRPGL 
09140C* § 1S ANY OTHER VALUE TURN ON IND 07 MRRPGL 
09150C* 3 CHECK VALID DATA IF NOT VALID TURN IND O7 ON MRRPG1 
O91 G00 ke OO 2 a ici iii goog takai tok MRR PGE 
0046 O9170C 04 EFFL COMP 8 O707 LEN XACTLY 8  MRRPGL 
0047 09180C 07 GOTO INVDAT MRRPG1 
0048 09190C 04 OPRATR COMP ‘48 1515141§ ADD WANTED MRRPGL 
0049 09200C 04 15 OPRATR COMP '-* O707151S SUBTRACT MRRPGL 
0050 10010C O4NO7 ‘TPIPT come o ae O07 VALID NUMBER MRRPG1 
LOO2ZOC Re eRe ii iii oii hoi Ci iO a go gO kak ide ida ioak MR RPG L 
10030C* MRRPG1 
10040C* IF INPUT IS NOT VALID GO TO INVALID DATA ROUTINE MRRPGL 
10050C* MRRPG1L 
LOO6OC #% 3 3% 3 tok Ro mR RR RO IO i iO aac iio iioiioiacikctok MR RPG 1 
0051 10070C 04 07 GOTO INVDAT MRRPG1 
LO080C 4k Rk ao oi io iki io OR RO I RC RR iio ok MR RP GL 
10090C* MRRPG1 
10100C* 1 FIND PROPER ACCUMULATOR MRRPG1 
10110C* 2 AOD DR SUBTRACT INPUT TO ACCUMULATOR MRRPG1L 
10120C* MRRPGL 
LOLBOC #¥ ee OE Ei RO ROR RO OR a oaokiok ok tokototett MRRP GL 
0052 10140C 04 14 ACMYyN ADD TPIPT ACMYyN ADD TO ACMLATR MRRPGL 
0053 10150C 04 15 ACMY,N SUB TPIPT ACMY »N SUB FROM ACMLTRMRRPG1 
LOLOOC HRERRRRR ERK IRR aOR Fok x kkk aK MRRP GL 
10170C* MRRPG1 
L0180C* DETERMINE IF THE ACCUMULATOR IS NEGATIVE-LESS THAN 0- MRRPGL 
10190C* TURN ON IND 16 WHICH ALLOWS A MINUS SIGN TO MRRPGL 
10200C* OVERRIDE THE PLUS SIGN ON OUTPUT SPECIFICATION MRRPG1 
11010C* MRRPG1 
1102 OC 8% & RR RI Oc cio tick ic diiok iooigioik lok doko io MRR PG 1 
0054 11030¢ O4ACMY SN COMP o 16 RESULT NEG MRRPGL 
110400 #30 ek ao aio aia iii aC CIO IOI zack ici iio ioioi ak ak dakok daiok ie deak de actokM RR PG 1 
11050C* MRRPGL 
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RPG Il 
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0055 
0056 
0057 
0058 


0059 


0060 
0061 
0062 
0063 
0064 
0065 


0066 


0067 
0068 
0069 


0070 
0071 


0072 
0073 


0074 
0075 
0076 
0077 
0078 
0079 


11060C* MRRPGL 
1.070 (3A OOO OI oldie ioiai aii iol gioick ici icici iii iolaiaiiaia ick iiciciaatixMe RP G1 


11080C OPTPUT TAG MRRPG1L 
11090C 18 SETOF 18 MRRPG1 
11100C 04 MOVE '52! TPRY43 OUT LEN MRRPG1L 
11110C 04 EXCPT SEND CURNT VAL MRRPG1 
111. 20 C3 Gao to maa tak taaiuii alk ial iaiaiaigioiai i gaia i fai ii igaiciak gtk ack ator MRR PG 1 
11130C* MRRPGL 
11140C* MRRPG1 
11150 Ce RR IO Io iO ii taigiok a lok midair i ack MR RPG 1 
111600 91 GOTO OPTERR NO GO TO ER RTNMRRPG1 
111700 aI Oi i a GIR aia ici i io ioli iiaiaick tolak aoick ack aio a ak MRRP G1 
11180C* MRRPGL 
11190C¥#* IF SUCCESSFUL DO INVITE INPUT FOR THIS TERM AND THEN GO TO ACCEPTMRRPG1 
11200C%* [INPUT FROM ANY ONE MRRPG1 
12010C* MRRPGL 
12020033 io Ke On eid oii ic a aio ietoioi aio iol ie i i loiok dott ar MR RPG 1 
12030C INVIT TAG MRRPG1L 
12040C Ol MOVE "§ EF TPRYs2 INVITE OP CODE MRRPG1 
12050C ol MOVE ‘22! TPRY+4 XPECTED MAX LENMRRPG1L 
12060C ol EXIT SUBR91 INVITE WITHOUT MRRPG1 
12070C RLABL TPRY SPECIAL MRRPGL 
12080C RLABL TNAME MRRPG1 
12.09.00 223 OO a a IGG iG goto iii ok anioiotoiaktotak ia MR RPG 1 
12100C* MRRPG1L 
12110C**ONLY NAME AND LENGTH NEEDED FOR INVITE.THIS COULD HAVE BEEN DONE MRRPGL 
12120C#*VIA EXCPT. IF SO SUBR91 WOULD NOT HAVE BEEN NEEDED. MRRPG1 
12130C* MRRPG1 
12.1400 RR IOC ISI IOR IR IOI RO RO GIO AIR ICO Ra ic iotolotaiiietotaioiai ice acaak MR RPG 1 
12150C ol GOTO ACPIPT GO ACCEPT INPUTMRRPG1 
1.2 160 CR GOO SII IO iar ROR ROI GOR ROI III ICR a aR RO Ia RR RI CCE HM RR PG) 
12170C%* MRRPGL 
12180C*****END OF MAIN LINEsSPECIAL ROUTINES FOLLOW. MRRPGL 
12190C* MRRPG1 
12.200 7 SOE GI RGU RIGOUR IOioi Rio Ro Rotor Ri RR Rok tt dice MRRP G1 
13010C* MRRPG1 
13020C** INPUT ERROR ROUTINECIPTER)-MINUS RETURN CODE. ENTERED ON INDICA- MRRPGL 
13030C** TOR 03 MRRPGL 
13040C** SUBROUTINE MRRPGL 
13050C* MRRPG1 
130600 * 30 IO II i iG i ii gio Cok icici toiaiainik doioiciotcdafioioi tack MR RPG 1 
13070C IPTER TAG MRRPGL 
13080C 03 EXSR CONSB TALK TO GPERATRMRRPGL 
13090C 13 GOTO RELEAS UPON RETURN 13 MRRPG1L 
13100 CO OO RUC IO IOI or io a IG a ai aa tai ii i ad tototok MRR PG 1 
13110C* MRRPGL 
13120C*MEANS RELEASE THIS TERMINAL. NOT 13 SAYS SEND MESSAGE AND INVITE. MRRPGL 
13130C* : MRRPG1 
13140 Ca GO IO OI Oi IOI I IR IO a toi ia lok sciaiiaakaicdiciatok MRRP G1 
13150C 18 MOVE '36' TPRY 53 OUT LEN MRRPG1 
13160C 18 EXCPT SEND MSG MRRPGL 
13170 CeO I ICO RG GIGI tolbiotoii iol iii ici ici ik talk MR RPG 1 
13180C* MRRPG1L 
13190C* SINCE NOWAIT WAS SPECIFIED NO RETURN CODE IS AVAILABLE TO CHECK. MRRPGIL 
13200C* MRRPGL 
140100 2 ROO RI IR OGIO OGIO OR a ok kai iiagoakaick MRR PG 1 
14020C 18 SETOF 18 MRRPGL 
14030C 03 GOTO INVIT MRRPG1L 
14040C** END OF IPTER MRRPGL 
16.0500 22 OI OR iabigigoiuiciogdcik tug otolik tokio aorMR RPG 1 
14060C* MRRPGL 
14070C** GUTPUT ERROR ROUTINE(OPTERR)-NON O RET CODE MRRPGL 
14080C* MRRPGL 
14.0900 2222 GIG IOI IOI IO i aici gigi ioioi a aii iii a a iii aioiaiaiciai oti aok a tok a 28M RR PG 1 
14100C OPTERR TAG MRRPG1 
14110 OL SETON 17 MRRPG1 
14120C 17 EXSR CONSB TALK TO OPERATRMRRPGL 
14130C 17 SETOF 17 MRRPGL 
14140C 13 GOTO RELEAS 13,RELS TERM MRRPGL 
14150C OL GOTO OPTPUT TRY AGAIN MRRPG1L 
14160C** END OF OPTERR MRRPGL 
14.1 700 II I I a I ROR ROI III a toi toioiototoiatototni i iaiai iio iio MR RPG 1 
14180C* MRRPGL 
14190C#* INVALID DATA ROUTINEC(INVOATI-~INPUT LEN NOT 8,INVALID OPERATOR, MRRPG1 
14200C#* (NOT Nyte-}e INVALID DIGITS ENTERED, ETC MRRPGL 
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15010C* MRRPGL 
150200 #8 RIC OI Rook i lcd kcktuk kok kak ick e MRRP GL 


0080 15030C INVDAT TAG MRRPG1 
0081 15040C ov SETON 18 MRRPG1 
0082 15050C 07 MOVE "36! TPRY 13 OUT LEN 18 MRRPGL 
0083 15060C 07 EXCPT TELL TERMINAL MRRPGL 
0084 15070C 07 SETOF 18 MRRPG1 
0065 15080C o7 GOTO INVIT INVITE MORE MRRPGL 
15090C* INPUT FROM THISMRRPGL 
15100C# TERMINAL MRRPGL 
15110C** END OF INVDAT ROUTINE MRRPG1 
15120C #3 ROI IG OG i ie i iok gio ick e tok bik ear MRRPGL 
15130C# MRRPG1 
15140C##RELEASE TERMINAL ROUTINE(RELEAS) RELEASES TERMS; CLEARS ATTACHED MRRPGL 
15150C#*LIST AND ACCUMULATOR LIST ENTRIES AND DETERMINES WHEN TO GO TO EQJMRRPGL 
15160C* MRRPG1 
15170C FOR I IO OG i ii a i a aC i iabok debi kk MR RPG 1 
0086 15180C RELEAS TAG MRRPG1 
0087 15190C 09 GOTO RELCLR CLEAR LISTS MRRPGL 
15200C* MRRPGL 
1601L0C# NOTE 09 MEANS A TERMINAL ATTACHED TO THIS PROGRAM HAS ENTERED MRRPG1L 
16020C* COMMAND INTERRUPT MODE AND ENTERED THE RELEASE COMMAND. MRRPGL 
16030C* : MRRPGL 
0088 16040C 13 MOVE ' K! TPRY +2 REL TERM OP CODMRRPG1 
0089 16050C 13 EXIT SUBROL MRRPGL 
0090 16060C RLABL TPRY MRRPGL 
0091 16070C RLABL TNAME MRRPG1 
0092 16080C RELCLR TAG MRRPGL 
0093 16090C 09 MRRPGL 
0094 16100COR 13 MOVE * '  ATRY®N CLEAR THIS NTRYMRRPG1 
0095 16110C 09 MRRPGL 
0096 16120COR 13 MOVE "000000" ACMY,N MRRPGL 
0097 16130C 09 MRRPG1 
0098 16140COR - 13 GOTO ACPIPT MRRPGL 
161 50 CO OO oto dc ial aiooioiiok a aa idiot icici ioiiok ek MR RPG 1 
16160C# MRRPGL 
16170C**SHUTDOWN ROUTINE (SHTDWN) 04 RET CODE. ISSUES STOP INVITES AND MRRPGL 
16180C#*SHUTDOWN MESSAGE TO ALL ATTACHED TERMS BEFORE GOING TO EOJ MRRPG1 
16190C# MRRPGL 
16200C SOIR i OKC a i a I kak iok tokio aeakMR RPG] 
0099 17010C SHTDWN TAG MRRPGL 
0100 17020C 06 SETON LISHUTDOWN IND MRRPG1 
0101 17030C SHDWNO TAG MRRPGL 
0102 17040C LIN ADD 1 N ADD TO INDEX MRRPG1 
0103 17050 LLATRYN come ' ' LOTERMINAL HERE MRRPG1 
0104 17060C 19 GOTO SHDWNL NG CHECK NEXT MRRPG1 
0105 17070C il MOVE ATRYsN TPRYy5 TNAME TO ARY MRRPG1 
0106 17080C 11 MOVE ' D At TPRY 72 STOP INVITE MRRPGL 
0107 17090C 11 MOVE ‘22° TPRY14 MAX XPECTO LEN MRRPGL 
0108 17100C ui READ TPCONSIO MRRPGL 
0109 17110C il EXSR RETCHK CHECK TRN CODE MRRPG1 
0110 17120C 09 GOTO SHOWN TERM CANCELLED MRRPG1 
0111 17130C 11 MOVE '48! TPRY +3 OUT LEN MRRPG1 
0112 17140C ll EXCPT APPROPRIATE MSGMRRPG1 
0113 17150C SHOWN1 TAG MRRPGL 


Note: When the last terminal attached to an MRT program is processed, issue a Release 
Terminal operation to that terminal in order to check the count of outstanding Invite 


Inputs. If the count is greater than zero, the program can issue an Accept Input operation. 


For example, suppose an MRT program is servicing the maximum number of requestors 
and one or more additional requests are queued to the program. If the program receives 
a shutdown-requested return code (04) and goes to end of job without checking the 
count of outstanding Invite Inputs, the program terminates with a 2C termination code 
(going to end of job with outstanding Invite Inputs) and each of the queued terminals 
receives an SO6 message (program cancelled — shutdown). 
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RPG Il 
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6-46 


0114 
0115 
0116 
0117 


0118 
0119 
0120 
0121 
0122 
0123 
0124 
0125 
0126 
0127 
0128 
0129 
0130 
0131 
0132 


0133 
0134 
0135 
0136 
0137 
0138 
0139 
0140 
0141 
0142 
0143 
0144 


0145 
0146 
0147 
0148 
0149 
0150 
0151 
0152 
0153 
0154 
0155 
0156 
0157 
0158 
0159 
0160 
0161 
0162 
0163 
0164 
0165 
0166 
0167 
0168 
0169 
0170 
O17L 
0172 
0173 
0174 
0175 
0176 
0177 
0178 


17160C LIN COMP 4 LROONE MRRPG1 
17170C NLR GOTO SHOWNO NO,NEXT TERM MRRPG1 
17180C LR GOTO END YES,EOJ MRRPG1 
17190C END TAG MRRPGL 
172000 A oO to tokio iii io oii doloiok ik doi iiiok loti dak doiok aok aekokaictcactcok MRRP G1 
18010C* MRRPGL 
18020C** RETURN CODE CHECKING ROUTINE (RETCHK) MRRPGL 
18030C* MRRPG1 
180400 eA aC RI RO iO aii igiam Git iaiooiaaiok kadai tokio MRRP G1 
18050CSR RETCHK BEGSR MRRPG1 
18060CSR Ol SETOF 060708 MRRPG1L 
18070CSR ol SETOF 0910 MRRPGL 
18080CSR OLRETCOD COMP 00 050304 MRRPG1 
18090CSR 03 MRRPG1 
18100COR 04 GOTO ENDRET MRRPG1L 
18110CSR O5RETCOD COMP 04 OBO706SHUT DOWN MRRPG1 
18120CSR 06 MRRPG1 
18130COR 07 GOTO ENDRET . MRRPGI 
18140CSR O8RETCOD COMP 08 O9TERM CANCELLED MRRPGL 
18150CSR NOORETCOD COMP 10 1OSTOP INVITE OKMRRPGL 
18160CSR NO9 MRRPG1L 
18170COR N1O SETON O7CATCHALL MRRPG1 
18180CSR ENDRET TAG MRRPGL 
18190CSR ENDSR MRRPG1L 
18200C¥*END OF RETCHK MRRPGL 
19010 0A ci ORI IORI GO UR GI aK aaa aR ai aa ior tok MRR PG 1 
19020C* MRRPG) 
19030C** CONSOLE I/O ROUTINE. MRRPGL 
19040C% MRRPG1 
190506 2 RIO IO IOI IOR II GOI CR tai aa iiiuictaiaiakiok MRR PG] 
19060CSR CONSB BEGSR MRRPGL 
19070CSR OL MOVE TNAME SAVE 6 SAVE TNAME MRRPG1 
19080CSR 91 SETON 81 CONSLO EXCPT MRRPGL 
19090CSR 91 SETOF 91 CLEAR NEG RETCOMRRPG1 
19100CSR 01 MOVE "47! TPRY+3 QUT LEN MRRPGL 
1OLLOCSR ol MOVE ‘16° TPRY54 MAX INPUT LEN MRRPG1L 
19120CSR OL EXCPT PUT CONSOLE MRRPG1L 
19130CSR 01 READ TPCONSIO GET CONSOLE MRRPGL 
19140CSR ol MOVE SAVE TNAME RESTORE TNAME MRRPG1 
19150CSR OLCONSIP COMP '"TAt 131318DOES OPERATOR -MRRPG1 
19160CSR 81 SETOF 81 MRRPGL 
19170CSR CONSE ENDOSR WANT TO MRRPGL 
19180C**END OF CONSB SUBROUTINE TRY, AGAIN MRRPG) 
200100TPCONSIOE 81 MRRPGL 
200200 TPRY 93 08 MRRPG1 
200300 04 'C! MRRPGL 
200400 14 "CONSOL' MRRPGL 
200500 o3 40 "INPUT TP ERROR TNAME-' MRRPGL 
200600 17 40 "OUTPUT TP ERROR TNAME-* MRRPGL 
200700 TNAME 47 MRRPGL 
200800 E 18 MRRPG1 
200900 TPRY,3 08 MRRPG1 
201000 04 'CF! MRRPGL 
201100 TNAME 14 MRRPGL 
201200 36 'TRY AGAIN! MRRPG1 
201300 a? 26 ‘INV DATAt MRRPGL 
201400 03 26 'TP ERROR! MRRPGL 
201500 E O4NLT7NO7 MRRPG1 
201600 TPRY+3 08 MRRPG1 
201700 04 'CB8! MRRPGL 
201800 TNAME 14 MRRPG1 
201900 30 "CURRENT VAL~' MRRPG1 
202000 31 f+? MRRPGL 
210100 31 '-! MRRPG1 
210200 52 "ENTER DATA! MRRPGL 
210300 ACMY sN3. 41 MRRPGL 
210400 — MRRPG1 
210500 TPRY3 08 MRRPGL 
210600 4 "CF! MRRPGL 
210700 ATRYsN 14 MRRPG1 
210800 28 "CCP SHTOWN® MRRPG1 
210900 38 "LAST REC-* MRRPGL 
211000 03 48 *TP ERROR? MRRPG1 
211100 07 48 "BAD DATA MRRPGL 
211200 OQ4O0PRATR 41 MRRPGL 
211300 O4TPIPT 48 MRRPGL 
211400 10 48 " NO DATAS MRRPG1 
211500* END OF PROG MRRPG1 
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INDICATORS USED 
LR OL 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 81 91 


EXECUTION TIME TABLES AND ARRAYS 


STMT# TABLE/ DEC ENTRY NUMBER OF OTT T/A 
DEFINED ARRAY POS LENGTH ENTRIES DISP OISP 
0004 TPRY 006 00005 0100 0020 
0005 ATRY 006 00004 0108 004B 
0006 ACMY 0 010 00004 0110 0009 
FIELD NAMES USED 
STMT# NAME DEC LGTH DISP 
0009 RETCOD O 002 OO06F 
0010 EFFL 0 004 0073 
0011 TNAME 006 0063 
0012 OPRATR 001 0064 
0013 TPIPT 0 007 OO7A 
0014 CONSIP 003 0067 
0019 N 0 001 0078 
0134 SAVE 006 0060 
LABELS USED 
STMT# NAME TYPE 
0015 ACPIPT TAG 
0025 LUPL TAG 
0033 LUP2 TAG 
0039 GOl TAG 
0041 G02 TAG 
0055 OPTPUT TAG 
0060 INVIT TAG 
0067 IPTER TAG 
0074 OPTERR TAG 
0080 INVDAT TAG 
0086 RELEAS TAG 
0092 RELCLR TAG 
0099 SHTDWN TAG 
0101 SHDWNO TAG 
0113 SHDWN1 TAG 
0117 END TAG 
0118 RETCHK BEGSR 
0131 ENDRET TAG 
0133 CONSB BEGSR 
0144 CONSE ENOSR 
ERROR NUMBER STATEMENT NUMBER 
RG 097 0008 
RG 558 0022 
RG 558 0108 
RG 558 0140 
ERROR SEVERITY TEXT 
2G O97 W NO FIELDS DESCRIBED FOR THIS OR PREVIOUS RECORD. 
2G 558 W INVALID USE OF, OR MISSING, RESULTING INDICATORS WITH THIS OP CODE. 


INVALID RESULTING INDICATORS BLANK. 


Figure 6-22 (Part 6 of 6). Example 2 — RPG II MRT Program 
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As an Assembler programmer, you must be famitiar with 
the information included in Chapter 2: Standard Appli- 
cation Program Interface to the CCP. To assist you in 
supplying codes needed for your source program, the CCP 
provides six macro instructions, each of which generates 
information needed by the source program. 


Four of these macros generate equates for values significant 
to communications under CCP: $NCOM, $NPLO, $NOPV, 
and $NRTV. The fifth macro — $NPL — generates a 
parameter list, and the sixth macro — $NCIO — generates 

a request for a communications operation. 


Each of the supplied macro-definitions is a member of 
the Source Library on your program-preparation pack. 


Note: Because several of these macros use macro processor 
facilities not available prior to version 08, modification 
level 00 of System/3 Model 10 Disk System Management, 
they should not be used for program preparation with an 
earlier version of the Macro Processor on that system. 


Symbols Used in Defining Macro Instructions 


The symbols [ ] and{ }are used in this publication to help 
define the macro instructions. You do not code these 
symbols; they are only used to indicate how a macro in- 
struction may be written. 


[ ] indicates an optional operand. The operand enclosed 
in the brackets may or may not be coded, depending 
on whether or not the associated option is desired. 

If more than one item is enclosed in brackets, for 


PUT’ 
coded, _ 


example get] either one or none of the items may be’ 


{ } indicates that a choice must be made. One of the 
operands from the vertical stack within braces, for 
example{y5°} must be coded, depending on which 
of the associated services is desired. 


Options that are underlined are the default values used by 
the CCP if you do not provide an operand. For example, 
for{¥/ES}, YES is the assumed value. 

For cases in which YES is appropriate, Y may be coded; for 
cases in which NO is appropriate, N may be coded. 


Chapter 7: Basic Assembler Programming for CCP 


For more information concerning the coding of macro 
instructions, see the following manuals: 


@ /BM System/3 Models 10 and 12 Control Programming 
Macros Reference Manual, GC21-7562 


@ /BM System/3 Model 15 System Control Programming 
Macros Reference Manual, GC21-7608 


Mhnotes 


Mnotes applicable to the supported Assembler macros are 
described at the end of this chapter. Each mnote descrip- 
tion addresses the severity of the problem, the issuing 
macro, an explanation of the problem, system action, 
and suggested programmer action. 


GENERATE EQUATES FOR COMMON VALUES 
($NCOM) 


The $NCOM macro generates a set of symbolic equates, 
each of which represents a value commonly used in CCP 
Assembler language communications programming. The 
symbols generated and the values they represent are: 


Symbol Decimal Value Value Represented 

$NIXR1 1 Index register 1 

$NIXR2 2 Index register 2 

$NSENT 4 Address of General Entry 

$NSCCR 1 DSM RIB for CCP 

$NSCCS 0 CCP sub-RIB for com- 
munications operation 

$NLPL 16 Length of a parameter 
list 

SNLPLF 2 Length of a parameter 
list field 

$NLSTN 6 Length of a symbolic 


terminal name 


This macro need be used only once in an assembly to 
generate the desired symbols. However, if this macro is 
used more than once in an assembly, duplicate symbols 
are not to be generated and no assembly error or error 
mnote is generated. A warning mnote is issued, however, 
each time this macro is used after the first use. 
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The symbols generated by this macro are used by the 
$NCIO macro. If the $NCIO macro is issued in an assembly 
and the $NCOM macro has not previously been issued, the 
$NCIO macro generates the symbols. However, each sub- 
sequent time the $NCOM macro is issued, a warning mnote 
is issued. 


The format of the $NCOM macro is: 


je | -_ 


Notes: 
®@ This macro has no operands, 


@ The name field of this macro is not used; any symbol 
entered in this field is ignored. 


GENERATE EQUATES FOR PARAMETER LIST 
OFFSETS ($NPLO) 


The $NPILO macro generates a set of symbolic equates. 

Each symbol generated represents a field in a parameter 
list, and is equated to the displacement (offset from the 
first byte of the parameter list) of the rightmost byte of 
that field. 


The symbols generated, and the fields they represent are: 


Symbol Decimal Value _ Field Represented 

$NPRTC 1 Return code field 

$NPOPC 3 Operation code/modifier 
field 

$NPOUL 5 Output data length field 
(see note) 

$NPEFL 5 Effective (actual) input 
data length field (see note) 

$NPATI 5 Attributes identifier 
field (see note) 

$NPINL 7 Maximum input data 
length field 

SNPRAA | 9 Record area address field 

SNPWKA 11 Internal work field 

$NPWKB 13 Internal work field 

$NPWKC 15 Internal work field 


Note: Symbols $NPOUL, SNPEFL, and $NPATI represent 
the same field within a parameter list and are equated to 
identical displacements. 
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This macro need be used only once in an assembly to 
generate the desired symbols. If used more than once, it 
does not cause duplicate symbols to be generated and no 
assembly error or error mnote is generated. A warning 
mnote is issued, however, each time this macro is issued 
after the first, 


The symbols generated by this macro are used by the 
$NCIO macro. If the $NCIO macro is used in an assembly 
but the $NPLO macro has not been previously issued, the 
$NCIO macro generates the symbols itself. However any 
subsequent use of the $NPLO macro only causes a warning 
mnote to be issued (duplicate symbols are not generated). 


The format of the $NPLO macro is: 





Notes: 
@ This macro has no operands. 


@ The name field of this macro is not used; any symbol 
entered in this field is ignored. 


GENERATE OPERATION CODE/MODIFIER VALUES 
($NOPV) 


The $NOPV macro generates a set of symbolic equates. 
Each symbol generated represents the value of a CCP com- 
munications operation code or operation modifier (see 
Appendix E for the hexadecimal values of the operation 
code/modifier combinations). The symbols generated, 
and the operation code or modifier each represents, are: 
Symbol Operation defined 

$NCAOC Acquire Command-mode Terminal 
$NCGET Get 

$NCPUT Put 


$NCPTG Put-Then-Get 

$NCPNW Put-No-Wait 

$NCINV Invite Input 

$NCACC Accept Input 

$NCSPI Stop Invite Get 

$NCGTA Get Terminal Attributes 

$NCACO Acquire Terminal 

$NCREL. Release Terminal 

$NCSHOQ Shutdown Inquiry 

$NCCPY Copy (3270 DFF only) 

$NCEAU Erase All Unprotected (3270 DFF only) 

$NCTCH Chain Task Request 
Modifier defined 

$NMMSG Send end-of-transmission 

$NMBLK End of current data block 

SNMRVI Send Reverse Interrupt 

$NMKPL Keep control of communications line 

$SNMSTA Set Terminal attributes 

$NMNNL Record does not start a new line (not New 
Line) 

$NMNEL Record does not end the current line (not 
End Line) 

$S$NMOVR Override/Selected Field List (3270 DFF only) 

$NMPRF Program request under format 


This macro need be used only once in an assembly to 
generate the desired symbols. If used more than once, this 
macro does not cause duplicate symbols to be generated 

and no assembly error or error mnote is generated. However, 
a warning mnote is issued each subsequent time this macro 

is issued in the assembly. 


The symbols generated by this macro are used by the 
$NCIO macro. If the $NCIO macro is issued in an assembly 
but the $NOPV macro has not previously been issued, the 
$NCIO macro generates the symbols itself. However, any 
subsequent use of the $NOPV macro only causes a warning 
mnote to be issued (duplicate symbols are not generated). 


The format of the $NOPV macro is: 


es 


Notes: 
@ This macro has no operands. 


@ The label field of this macro is not used; if a symbol 
is specified in the label field, it is ignored. 


GENERATE EQUATES FOR RETURN CODE VALUES 
($NRTV) 


This macro generates a set of symbolic equates. Each 
symbol generated represents the two-byte signed numeric 
value of a return code issued by CCP. The symbols gen- 
erated, and the meaning and value of the return code 
specified by each, follow: 
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Type of 
Return Code Symbol 


No error or $NOK 
exception. $NACTC 


Exception $NXDTR 
$NXEOT 
SNXEDT 
$NXSHD 
$NXDPD 
$NXRVI 
$NXCLR 
$NXNAV 
“$NXOFF 
$NXSPI 
$NXNAQ 
$NXMAX 
$SNXTCP 
SNXADT 


$NRDCK 
$NRTRN 
$NRLST 
$NRPBS 
$NRABN 
$NRXRA 
$NRATO 
$NRTTO 
$NRWTO 
$NRNOC 
$NRUD 
SNRABD 
$NRADC 
$NRNAK 


Error $NR2DU 
(3270 only) $NR2ED 
$NR2TE 
$NR2CD 
$NR2PD 
$NR2PO 
$NR2PB 
$NR2PC 


$NR2PI 
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Return 


Code 
Value 


Meaning 


Successful operation 
Successful chain task data accept operation 


Data truncated 

EOT received/non-PRUF data returned to PRUF program 
EOT received and data truncated 

Shutdown requested 

Data pending on BSCA line 

RVI/Terminal Interrupt received 

3270 CLEAR key 

Terminal no longer available 

Terminal offtine 

Stop Invite Input successful 

Acquire terminal failed 

Maximum number of chain task requests already queued 
Insufficient TP buffer available for this request 

Chain task data was truncated 


Data check 

Invalid character 

Lost data 

Permanent BSCA error 
Abnormal response 
Transmit/Receive abort 

No response to polling/addressing 
Text timeout 

Wait time exceeded 

No connection 

Invalid 1D 

Abort, disconnect 

‘Adapter check 

Negative response to addressing 


Device unavailable or not ready 

Equipment check, device end 

Terminal control unit detection of BSCA error 
Control check, data check 

Data check on Copy command 

Operation check on Copy command 

Device busy on Copy Command 

Control check, operation check, data check on 
Copy Command 

Invalid data received from 3270 using DFF 
(Get, Accept Input, Stop Invite Input operations) 





Return 
Type of Code 
Return Code Symbol Value 





Error $NR5SR 
(3735 only) $NR5IC 
$NR5BF 
$NR5DF 
$NR5RF 
$NR5UH 
$NR5DE 


Error $NR7TE 
(3741, 5234, $NR7NA 
and 5235) $NR7DC 
$NR7LB 
$NR7WL 
$NR7RP 
$NR7SC 
$NR7DO 
$NR7BE 
$NR7BT 
$NR7LE 
$NR7NF 
$NR7SE 
$NR7RE 
$NR7WE 
$NR7NR 
$NR7WP 


For more information concerning these return codes, and 
recommended user actions, see Appendjx E: Return 
Codes. 


This macro need only be used once in an assembly to 
generate the desired symbols. If it is used more than once, 
duplicate symbols are not generated and no assembly error 
is forced. However each subsequent time this macro is 
used, a warning mnote is issued. 


Meaning 


Attempted send before receive 
Invalid character 

3735 buffer overflow 

- Disk full 

Directory full 

Undefined header 

3735 disk error 


Transparency error occurred 
No activity in 20 seconds 
Data check 

Received line bid error 
Wrong length error 

Reset was pressed on 3741 
Security check 

Disk overflow 

Bad extent error 

Both stations transmit 
Length error 

No record found on disk 
Seek error 

Read error 

Write error 

3741 not ready 

Diskette is write-protected 


The format of the $NRTV macro is: 


Notes: 

1. This macro has no operands. 

2. The label field of this macro is not used; if a symbol is 
specified in the label field, it is ignored. 
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GENERATE PARAMETER LIST ($NPL) 


The $NPL macro generates a communications parameter 
list. You can specify the initial value of each field of 

this list. This macro may be used any number of times in 
an assembly; a separate parameter list is generated each 
time this macro is used. When the parameter list is gen- 
erated, the operand values specified are not checked for 
validity; therefore, care must be taken that only valid 
operands are specified. 


The format of the $NPL macro is: 










[ label } SNPL { OP—valuex ] 
oe 
[ elles 
[ ,INLEN-valuex ] 


[ ,RECA-addrx | 





See Note under $NCIO macro for the meaning of va/uex 
and adarx. 


If you specify a label with the $NPL macro, an EQUATE 

is generated. This EQUATE sets the specified syrnbol equal 
to the address of the first byte of the parameter list 
generated. 


OP-valuex specifies an initial value for the operation/ 
modifiers field of the parameter list. If this operand is 
omitted, a value of X'0000’ is generated for the operation/ 
modifiers field. 


The operand value should represent a valid CCP operation. 
Any valid absolute expression may be used, but it is 
recommended that operation and modifier values generated 
by the $NOPV macro be used. 


OUTLEN-valuex specifies an initial value for the output 
data length field. If this operand is omitted (and the 
ATTRID operand is also omitted), a value of X‘0000’ is 
generated for the output data length field. 


Because the output data length field (generated by OUTLEN) 
and the attributes identifier field (generated by ATTRID) 
occupy the same locations in the parameter list, both 
operands cannot be specified in one macro instruction. 

If both are specified, an error mnote is generated. 


The operancl value may be any valid absolute expression. 
Note that a data length entry does not include the six- 
byte symbolic terminal name found at the beginning of a 
record area. 
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ATTRID-valuex specifies an initial value for the attributes 
identifier field of the parameter list. If this operand is 
omitted and the OUTLEN operand is also omitted, a value 
of X’0000’ is generated for the attributes identifier field. 


Because the attributes identifier field generated by ATTRID 
and the output data length field (generated by OUTLEN) 
occupy the same locations in the parameter list, both 
operands cannot be specified in one macro instruction. If 
both are specified, an error mnote is generated. The operand 
value, which may be any valid absolute expression, should 
represent a positive number that corresponds to the 
identifier of a terminal-attributes set that has been defined 
for your installation. This definition is performed in a CCP 
Assignment Build run by a // TERMATTR statement. 


INLEN-valuex specifies an initial value for the maximum 
input data length field of the parameter list; if this operand 
is omitted, a value of X‘0000’ is generated for that field. 


This operand, which may be any valid absolute expression, 

should represent a positive number which is no greater than 
the length of the data portion of the record with which this 
parameter list will initially be used. The six-byte symbolic 

terminal name at the beginning of the record area is not in- 

cluded as part of the input data length. 


RECA-adarx specifies an initial value for the record area 
address field in the parameter list; if this operand is omitted, 
a relocatable value equal to the beginning of the parameter 
list plus 16 is generated for that field. 


This operand, which may be any valid relocatable expression, 
should represent the high-order (leftmost) byte of the record 
area. Note that the high-order byte of the record area is 

the leftmost byte of the name field in the record area, not 
the address of the first byte of the data portion of the record 
area. 


Each time this macro is used, a 16-byte parameter list 
(composed of eight successive 2-byte DC fields) is generated. 
Any fields which will not be affected by the operands of 
this macro are set to X‘0000’. If you specify a label in this 
macro instruction, the specified symbol is equated to the 
address of the high-order (leftmost) byte of the generated 
parameter list. No additional symbols are generated by this 
macro. You can cause symbols to be generated for offsets 
of fields within a parameter list by issuing a SNPLO macro 
instruction or by issuing a $NCIO macro instruction without 
issuing a $NPLO macro instruction. 


Example 


In the following example, initial values are placed in a 
parameter list using the $NPL macro: 





IBM System/3 Basic Assembler Coding Form 
IBM 
PROGRAM 
PROGRAMMER 
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Operation 


Remarks 
9 10 11 12) 13/14 15 16 17 18 19 


Operand 
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As a result of issuing the $NPL macro as shown above, a 
parameter list is generated with the operation code set to 
Accept Input, the maximum input length set to 20, and 
the address of the record area set to the address of INPUT 
(a record area defined elsewhere in the program). 
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SET CONTROL INFORMATION FOR COMMUNICATIONS 
OPERATION (SNCIO) 


The $NCIO macro provides control information needed to 
identify a communications operation and request CCP to 


perform that operation. 


The format of the $NCIO macro is: 


$NCIO [ PLIST— 


addrx 

dispx(,regx) 

(1) ] 
(2) 

(addrx) 

(dispx (,regx)) 


GET LRVI] 

cauwterteragt! INNLILNEL] LOVR] LPRF] 
PNW) (MSG 

PTG[,NNL] [,NEL] 

INV 

ACC 

SPI 


GTA 

CMD 
aca |, STA {1 
REL[,KPL] 
CPY 
EAU 
SHO 
TCH 
WAT 
valuex 
(1) 
(address) 
(dispx(,regx)} 


| OP— 


addrx 
OUTLEN( — J(1) 
|, )ATTRID (addrx) 


(dispx (,regx)) Note: The following operand forms 


must be enclosecl in apostrophes: 


[.INLEN — 


(addrx) ‘chars’ (TNAME — operand} 


{dispx (,regx)) ‘(dispx (,regx))’ 


(addrx) 
(dispx(,regx)) 


chars 

(addrx) 
(dispx(, ae 
ot 


[ ,.TNAME— 


valuex 
(1) ] ‘operation,modifier’ (OP — operand) 


[ ,EXEC— 


addrx 
[ -RECA— : 
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Notes: 


All operands in this macro are optional. 


Several syntactic classes are included in these descriptions, 
and are defined as follows: 


valuex — an absolute expression representing a number 
whose assembled value will fall in the range 
0 < value < 32,767 


dispx -- an absolute expression (representing a dis- 
placement from a base address) whose 
assembled value will fall in the range O << 
value < 255. 


regx — an absolute expression (representing the 
number of an index register) whose assembled 
value will be either 1 or 2. 


addrx - arelocatable expression representing a main- 
store address in your program. 


chars — one to six alphameric characters. 
Certain operand values may be written with surrounding 


parentheses to specify indirect addressing. If the first 
character of such an operand value is a left-parenthesis, 


the last character of that value must be a right-parenthesis. 


If this is not the case, an error is issued and the macro 
instruction is not generated. 


If an operand value is written enclosed in parentheses, 
the total number of characters within the parentheses 
must not exceed 16; if the number of characters exceeds 
16, an error is issued, and the macro instruction is not 
generated. 


The $NCIO macro can be used any number of times 
within an assembly. ; 


If you specify a label in the $NCIO macro instruction, 
an equate is generated. This equate sets the specified 
symbol equal to the address of the first byte of the 
first instruction generated. 


@ The first time a $NCIO instruction is used in an assembly, 
any or all of three sets of symbolic equates may be 
generated. If any of three macros (6NCOM, $NPLO, or 
$NOPV)} had not been issued before in that assembly, 
any equates which would have been produced by that 
macro are generated by the $NCIO macro. Any sub- 
sequent issuance of any of these macros produces a 
warning mnote, 


@ Inthe generation of the $NCIO macro, no check is made 
that any expression is syntactically valid to the Assembler, 
nor that the value generated is valid for its intended use. 


addrx 
dispx(,regx) 

{ PLIST (1) 
(2) 
(addrx) 
(dispx(,regx) ) 


The PLIST operand specifies the address of the high-order 
(leftmost) byte of the communications parameter list being 
used. 


When a request is made of CCP to perform a communications 
operation, the address of the parameter list used with this 
operation must be in index register 2. Therefore, you must 
either ensure that the address of your parameter list is in 
index register 2 when the instructions generated by this 
macro are executed, or code this operand in order to set 
index register 2 to the appropriate operand. 
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Omit this operand or code (2) to signify that index register 
2 already contains the address of the parameter list. 
Specifying a value of other than (2) causes an instruction 
to be generated which loads index register 2 with the para- 
meter fist address you specify. The source of this address 
is determined by the form in which you specify the 
operand: 


Form Index Register 2 set to: 
addrx The value of the expression itself. 
dispx(,regx) An address equal to the value of the 


specified displacement added to the con- 
tents of the specified index register. 
(1) The contents of index register 1. 
(addrx) The contents of a 2-byte field in main 
storage whose rightmost byte is located 
at the specified address. 
The contents of a 2-byte field in main 
storage whose rightmost byte is located 
at the specified displacement from an 
address contained in the specified index 


(dispx (,regx)) 


register. 

GET[,RVH 

PUT BLK 
euutCeeD [,NNL] [,NEL] [,OVR] [,PRF] 
PTG [,NNL] [,NEL] 
INV 

ACC 

SPI 

GTA 

acat.{ ee 

L.OP STA 

REL[,KPL] 
CPY 

EAU 

SHO 

TCH 

WAT 

valuex 

(1) 

(address) 
(dispx(,regx)) 


Note: if one (or more) modifiers is specified, the entire 
operand must be enclosed within apostrophes (for example, 
OP-’PUT,IMSG’). 


The OP operand specifies the setting of the operation field 
of your parameter list. If this operand is omitted, no 
instructions are generated to set the operation field. 


This operand can identify the actual value to which the 
field is to set, by specifying: 


® an abbreviation of an operation code, and any desired 
associated modifiers (see Appendix D for meanings of 
the abbreviations). 


® an absolute expression 


@ the name of a location from which the field’s value can 
be obtained when the instruction is executed. 


If the abbreviation of an operation code is used, the field is 
set to the proper numeric value for that operation (and 
associated modifier). If one or more modifiers are specified, 
each must be preceded by a comma; in addition, the entire 
operand must be enclosed within apostrophes to prevent 
the Macro Processor from interpreting the operation code 
and the (first) modifier as a delimiter of the operand. For 
example, if you specified NNL for the PTG operand, it 
would be coded OP-‘PTG,NNL’, 


If several modifiers are used they may be specified in any 
order after the operation code. In the generation of this 
macro, no check is made to determine if a valid modifier 
is used with the operation code. 


If the operand value begins with a left-parenthesis, it 
indicates that the value to be set into the operation field 
is to come from a specified location when the generated 
instruction is executed. This location is determined as 
follows: 

If the form is The field is set to 

(1) The contents of index register 1. 
(addrx) The contents of 2-byte field in main 
storage the rightmost byte of which 
is located at the specified address. 
The contents of a 2-byte field in 
main storage, the rightmost byte of 
which is located at the specified dis- 
placement from the specified index 
register. 


(dispx (,regx)) 


If the operand value is neither a 3-character operation code 
abbreviation (with or without modifiers) nor an expression 
beginning with a left-parenthesis, it is assumed to be an 
absolute expression, the assembled numeric value of which 
is to be set into the operation field. 


valuex 
Saat —)(1) 
ATTRID (addrx) 


(dispx(,regx}) 


These optional operands allow you to specify either the 
setting of the output data length field (if OUTLEN is 
specified). If both operands are omitted, no instructions 
are generated to set the field (the attributes identifier 

field and the output data length field are the same field in 
a parameter list). If both OUTLEN and ATTRID are 
specified in the same macro instruction, an mnote is issued, 
and the macro instruction is not generated. 


The operand may specify either the actual value to be set 
into the field, or a location from which the value can be 
obtained at the time the instruction is executed. The 
source of the value is determined by the form in which the 
operand value is specified: 

If the form is The field is set to 

valuex The value of the expression itself. 
(1) The contents of Index Register 1. 


(addrx) The contents of a 2-byte field in 
main storage, whose rightmost byte is 
located at the specified address. 
(disp(,regx)) The contents of a 2-byte field in main 


storage, whose rightmost byte is located 
at the specified displacement from an 
address contained in the specified index 
register. 


valuex 

(1) 
[ INLEN —)(addrx) 

(dispx(,regx)) 


This operand specifies the setting of the maximum input 
data length field of your parameter list. If this operand is 
omitted, no instructions are generated to set this field. 


The operand may specify either the actual value to be set 
into the field, or a location from which the value can be 
obtained at the time the instruction is executed. The source 
of the value is determined by the form in which the operand 
value is specified. The possible forms and the resultant 
setting of each follow. 


Operand form Resultant setting 

valuex The value of the expression itself. 

(1) The contents of Index Register 1. 
(addrx) The contents of a 2-byte field in 
main storage, whose rightmost byte is 
located at the specified address. 

The contents of a 2-byte field in main 
storage, whose rightmost byte is 
located at the specified displacement 
from an address contained in the 
specified index register. , 


(dispx(,regx)) 


addrx 

(1) ] 
[RECA —)(addrx) 

(dispx(,regx)) 


This optional! operand specifies the setting of the record area 
address field of the user's parameter list; if this operand is 
omitted, no instruction is generated to set that field. 


The operand may specify either the actual address to be 
set into the field, or a location from which the address can 
be obtained at the time the instruction is executed. The 
source of the address is determined by the form in which 
the operand value is specified. The operand forms used, 
and the field setting for each follow. 

Operand form Field set to 

addrx The value of the expression itself. 
(1) The contents of Index Register 1. 


(addrx) The contents of a 2-byte field in 
main storage, whose rightmost byte is 
located at the specified address. 

(dispx (,régx)) The contents of a 2-byte field in main 


storage, whose rightmost byte is lo- 
cated at the specified displacement 
from an address contained in the 
specified index register. 
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chars 
[,TNAME — < (addrx) ] 
(dispx (,regx) ) 


This optional operand specifies the setting of the name of 
the program to be requested or the symbolic terminal 
name in the name field of the user’s record area. When 
this operand is specified, instructions are generated to set 
the field; these instructions make use of the record area 
address in the parameter list as a pointer to the leftmost 
byte to which the specified name should be moved. {fa 
RECA operand was specified in this macro instruction, 
the record area address specified by that operand is used; 
if a RECA operand was not specified in this macro instruc- 
tion, the address presently contained in the record area 
address field of the parameter list is used. If this operand 
is omitted, no instructions are generated to set the pro- 
gram or the symbolic terminal name in the narne field. 


The operand can specify the program or symbolic terminal 
name to be set into the field, or a location from which 

the name can be obtained at the time the instruction is 
executed. The source of the name is determined by the 
form in which the operand value is specified. The possible 
forms of these operands, and the field setting generated 
by each follow. 


Operand form Field set to 
chars The character string specified. 
(addrx) The contents of a 6-byte field in 


main storage, whose rightmost 
byte is located at the specified 
address. 

The contents of a 6-byte field in 
main storage, whose rightmost byte 
is located at the specified displace- 
ment from an address contained 

in the specified index register. 


(dispx(,regx)) 
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YES 


[,EXEC — 
NO 


This optional operand specifies whether or not (after 
setting any control fields specified in other operands of 

the $NCIO macro instruction) instructions are generated to 
cause control to be transferred to CCP to perform the oper- 
ation. {f YES (or Y) is specified, or if this operand is 
omitted (YES is the default value), instructions are genera- 
ted to request the CCP to perform the operation specified 
py the programmer, using information either set by this 
macro instruction or already available in your parameter 
list and record area. 


lf a NO (or N) is specified, no branch is made to General 
Entry, and no RIB and sub-RIB generated. You might 
choose to specify this option when you only want to set 
certain fields in your parameter list or record area, but you 
won't be performing the operation until! a later point in 
your program. , 


Examples of Using $NCIO 


Figure 7-1 shows several examples of valid $NCIO macro 
instructions as you might code them in a program. The 
examples show various ways of specifying keyword operands 
for the macro. After issuing the $NCIO macro instruction, 
your program should test the return code to determine 
whether the operation was successful or whether it resulted 
in an error or exception condition. Return codes are 
summarized in Appendix E. 


Use of the $EOJ system macro instruction is also shown in 
Figure 7-1. You can use non-CCP System/3 macro instruc- 
tions in your CCP programs. These System/3 macro in- 
structions are described in: 


© /BM System/3 Models 10 and 12 Control Programming 
Macros Reference Manual, GC21-7562 


@ /BM System/3 Model 15 System Control Programming 
Macros Reference Manual, GC21-7608 





IBM Systam/3 Basic Assombler Coding Form 




















































































































PUNCHING GRAPHIC 
mstructions Ty acy 











are \VED 




































































































































































































































































































































































































































= 
> : 
- = I i O ' T 
wv a = hs 
ep 2 aS i 3 
Se = 2 —_—_>= nena a. a is 
ae oa eH 
i be ! foo ! i 
oo =z=_ FS =a WwW VV ! L_| : 
ee — 9 oO is i wu = c i 
ae fo 1 O i r t 
[a = Se (EEE EE 
= e aS ot wy x i us Me ee 
= 2 = -¥ =< = > aT d 
g had w o ! 
: azo a 5 x TT = 
5 ! = = 7 > - gq aS 
e 3a S 3 a5 > 
ye 3 eons ce 
See 4 a5 = 
= oS ws 5 : 
@ << & z =< So : wo e “k= = 
a z T — 4_ ¢ z a “o_o ~~ 
; =a g a4 oz = 
5 : : ' 
Te wt 38 a 4 :s T= ray 
“wy & ww) —_- = 2 = I 
2 t f—=—s = = (Fe Z 
8 <_T E >t Se a 4 Fe Te 
al | oe a oe | ee oa oe 
1 xe oa i -- ZZ a 
g : So ? int t aim 2 ? _j2 
Rg __ oe <=, +f. w a bb own oe. __& 
sl. a 73S an Aro eo o+ Wl oO- z 
g = = a wep i = ae as as = 
| aw i y > 4a 9 Zz 
cE 2— = E <i Fs Ad 
Be. __ oe a WAZ Zz Wz J 
g i Tz = eS A i -— oOo. — 9 wy 
. — s => mat ! } ww So we 
o Sa. —e= 
TE t tere ual ye : 
6 en ine EK 
VE) ee | 
We eee oO 
Usa Sa = 
<a = Oo i [-™ 
3 
oF 
a 
Lt 
a | 
[ Tz : 




































































e 



































































































































Figure 7-1. Examples of $NCIO Macro Instructions 
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Basic Assembler Programming for CCP 


PROGRAMMING RESTRICTIONS 


The following restrictions apply when programming for 
the standard interface to CCP using Assembler Language. 


® Input/Output cannot be performed on either the 5471 
Printer/Keyboard (Model 10 Disk System and Model 12) 
or the CRT/Keyboard (Model 15) using the standard 
DSM Data Management; instead, the console must be 
addressed as the “‘terminal’’ CONSOL, governed by the 
standard CCP restrictions concerning operations that 
may be performed on that device. (See the Standard 
Communications Interface for a description of these 
restrictions.) 


@ Ifthe (dispx(,regx}) operand format is used in the $NC- 
10 macro with index register 1 as regx, the original value 
of index register 1 is not returned after using the macro. 
Therefore, you should save and restore the register when 
using $NCIO. 


@ User DTFs and 1OBs must be placed in the first 24K of 
the user program. 


ASSEMBLER MACRO SUPPORT MNOTES 


Mnotes are error messages pertaining to macro instruction 
formats. They are included in your assembly listing, printed 
beneath the macro instruction to which each applies. 

The Mnotes which follow are issued if an error is encountered 
when using the Assembler Language support macros, 


N2001 CONFLICTING OPERANDS—OUTLEN/ATTRID 


Severity: Error (08) 
Issuing macro(s): $NPL,$NCIO 
Explanation: if a $NPL or $NCIO macro 


instruction, you have specified 
both the OUTLEN and the 
ATTRID operands. Because the 
output data length field (speci- 
field by OUTLEN) and the 
attributes identifier field 
(specified by ATTRID) are the 
same field in a parameter list, 
they are mutually exclusive, 
and only one can be specified at 
a time. 


System Action: 


Programmer Action: 


This macro instruction is not 
generated. 


Correct the macro instruction by 
using only one of the two oper- 
ands, and repeat the macro- 
generation/assembly run. 


N3001 INVALID OPERATION CODE SPECIFIED 


Severity: 
Issuing macro: 


Explanation: 


System Action: 


Programmer Action: 


Error (08) 
$NCIO 


The parameter specified in the 
OP operand is in the form which 
indicates an operation code 
followed by operation modifiers. 
However, the first element of 
the list is not a valid operation 
code abbreviation. 


This macro instruction is not 
generated. 


Correct the parameter by using 

a valid operation code and repeat 
the macro-generation/assembly 
run. 


N3002 INVALID OPERATION MODIFIER SPECIFIED 


Severity: 
Issuing macro: 


Explanation: 


System Action: 


Programmer Action: 


Error (08) 
$NCIO 


The parameter of the OP 
operand is in the form which 
signifies an operation code 
followed by one or more oper- 
ation modifier. However, an 
operation modifier specified is 
not a valid abbreviation. 


This macro instruction is not 
generated. 


Correct the parameter by speci- 
fying a valid operation modifier 
abbreviation and repeat the 

macro-generation/assembly run. 


N3003 PARAMETER MISSING FINAL RIGHT-PAREN 


Severity: 
Issuing macro: 


Explanation: 


System Action: 


Programmer Action: 


Error (08) 
$NCIO | 


An invalid form for a parameter 
was specified. The first character 
was a left parenthesis, but the 
last character was not a right 
parenthesis. 


This macro instruction is not 
generated. 


Correct the parameter by enclosing 
it properly with a right parenthesis 
and repeat the macro-generation/ 
assembly run. 


N3004 PARENTHES!IZED PARAMETER TOO LONG 


Severity: 
Issuing macro: 


Explanation: 


System Action: 


Programmer Action: 


Error (08) 
$NCIO 


A parameter enclosed by 
parentheses was composed of 
more than 16 characters (ex- 
cluding the parentheses). 


This macro instruction is not 
generated. 


If the error was due to a key- - 
punching error, correct the 
parameter and repeat the macro- 
generation/assembly run. If the 
error was due to an overly 
complex expression being coded 
within the parentheses, simplify 
that expression (by creating an 
equate for it), use the newly 
created symbol with the paren- 
theses, and repeat the macro- 
generation/assembly run. 


N6001 OFFSET VALUES PREVIOUSLY GENERATED 


Severity: 


Issuing macro: 


Explanation: 


System Action: 


Programmer Action: 


Warning (04) 
$NPLO 


A $NPLO macro instruction was 
used but the offset equate values 
to be generated from it had 
previously been generated in this 
assembly (either by another 
$NPLO macro instruction or by a 
$NCIO macro instruction). 


The offset equates are not 
generated; to avoid creation of 
duplicate symbols in this 
assembly. 


None required. 


N6002 OPERATION VALUES PREVIOUSLY GENERATED 


Severity: 
Issuing macro: 


Explanation: 


System Action: 


Programmer Action: 


Warning (04) 
$NOPV 


A $NOPV macro instruction was 
used, but the values to be gen- 
erated by it had previously been 
generated in this assembly (either 
by a $NOPV macro instruction 

or by a $NCIO macro instruction). 


Operation code and modifier 
value equates are not generated 
by this statement; to avoid crea- 
tion of duplicate symbols in the 
assembly. 


None required. 
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N6003 RETURN-CODE VALUES PREVIOUSLY 
GENERATED 


Severity Warning (04) 
Issuing macro: $NRTV 
Explanation: AS$NRTV macro instruction was 


used, but the return code value 
equates to be generated from it 
had previously been generated in 
this assembly. 


System Action: Return code value equates are 
, not generated; to avoid creation 
of duplicate symbols in this 
assembly. 


Programmer Action: None required. 


N6004 COMMON VALUES PREVIOUSLY GENERATED 


Severity: Warning (04) 
Issuing macro: $NCOM 
Explanation: A $NCOM macro instruction 


was used, but the common equate 
‘values to be generated from it 
had been generated in this 
assembly (either by a $NCOM 
macro instruction or by a $NCIO 
macro instruction). 


System Action: Common equate values are not 
generated by this macro instruc- 
tion: to avoid creation of dupli- 
cate symbols in this assembly. 


Programmer Action: None required. 
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PROGRAMMING A USER SECURITY ROUTINE — 
MODELS 10 AND 12 


The user of CCP may, if he chooses, write his own terminal 
sign on security routines rather than use the CCP password 
facility supplied with his system. To implement and use 
such routines, the following must be considered. 


This option must be selected at generation time by the 
“SECURE-USER” operand of the $ESEC statement. 


The security data which wil! be used at terminal sign 
on time by the security routines must have been 
previously written to the security module $CC4Z9 
by User Security Data Program, $CCPAU (see CCP 
System Reference Manual). 


The user security routines must be written in Basic 
Assembler Language (or an equivalent machine-level 
lJanguage) and must be structured such that they comprise 
four basic parts (statement numbers refer to the sample 
program, Figure 7-2): 


1. System equates. They provide the necessary 
offsets and pointers to various system tables, as 
well as other common equates. 


2. The transient prologue and equates. The function 
of this code is to provide the following: 


a. a temporary two-byte offset value pointing to 
the relocatable address constants (statement 
1087) 


b. a one-byte offset to the first executable instruct- 
ion (1091) 


c. a one-byte ID with a binary value of 1, which 
defines the CCP transient area in which this 
transient will be running (1092) 


d. a two-byte field of hex 0000 to permit the 
” passing of a parameter from this transient 
to another (1094) 


e. a two-byte displacement from the beginning 
of this module pointing to the first character 
past the ID of the transient to be called next 
(1095) 


f, the two-character ID of the transient to be 
called next (last two characters of the module 
name) (1097) 


g. three bytes for disk control which are used 
when this transient is read from disk (1098- 
1099); the first byte is always 7, the second 
and third bytes are set by CCP startup with | 
the cylinder/sector address of the transient 
specified by the two-character transient 1D. 

A one-character delimiter ($) and the two-byte 
ID of this transient follow (1100-1101). 


The main body of code, which in this example 
begins with statement 1108 and ends with state- 
ment 1191. This sample code will: determine the 
length of, and move the sign-on data to an area 
within this transient; determine which terminal 

is attempting to sign on and then verify the sign- 
on data for that terminal, as found in the user 
security work area; pass the result of the verifica- 
tion to the CCP sign-on transient, $CC4SO, by 
setting a value in ‘““TAXPRM” prior to exiting from 
this transient, The ‘““TAXPRM” field of any CCP 
transient (at relative locations 4 and 5 of the 
transient) is the field in which one transient passes 
information to another. The total length of parts 
2 and 3 cannot exceed hex length 1FF. 


Relocation Address Table. 


Because any sign-on security routine you write 

is a CCP transient, your routine must conform to 
the special way in which the addresses in CCP 
transients are established and relocated. 


In this special relocation method, any (two-byte) 
address, used in an instruction, which refers to a 
location within your transient itself requires an 
entry in a table, at the end of your transient, 

called the Relocatable Address Table. This method 
also allows you to address elements, outside your 
transient, which are in the CCP Communications 
Area; it also permits you to use any of a selected 
set of addresses which refer to routines or areas 
within the remainder of the CCP resident code. 
Any use of either of these types of addresses also 
requires an entry in the Relocatable Address Table. 
In effect, any use of a two-byte address which does 
not refer to an absolute location requires an entry 
in this table. 


In this method, any address you code in an 
instruction is entirely replaced, when CCP begins 
to run, by an address derived from an entry in 
the Relocatable Address Table. There must be 
exactly as many entries in this table as there are 
relocatable addresses in your transient. Further 
the first relocatable address in your transient 

is replaced by an address derived from the first 
Relocatable Address Table entry, the second 
relocatable address by an address derived from the 
second entry, and so forth. Thus; if you wish to 
make any of the three kinds of address references 
described in the previous paragraph, it does not 
matter whether, in an instruction, you code an 
appropriate relocatable address, but only that 
you code an appropriate entry in the table. 


Each Relocatable Address Table entry is of one 
of three types, depending on the type of address 
you need to use in the corresponding instruction: 


a. Address within the transient 
b. Address within the CCP Communications Area 
c. Address of a special routine or area 


Each entry is two bytes long. The form of each 
entry is as follows: 


Address within transient: The entry must contain 
the displacement of the location within the trans- 
ient being referred to. For example, the entry 

at statement 1198, corresponding to the address 
within the instruction at statement 1144, repre- 
sents a reference to the location 0042 within the 
transient. The two-byte displacement is formed in 
table entry by subtracting the address value of 

the beginning of the transient (SCC4YA) from the 
address within the transient being referred to 
(YA0100). 


Address within CCP Communications Area: The 
entry must contain the hex value COxx, where xx 
is the displacement within the Communications 
Area of the element being addressed. In this 
example, the symbol “COM” has been equated to 
the value X’C000’, and the symbol “@TUSTG” 
has been defined (by the macro $ECOM) as repre- 
senting the displacement of that field in the 
Communications Area which contains the address 
of the Terminal Unit Block for the terminal 
attempting to sign on. Thus, the table entry at 
statement 1196, corresponding to the address used 
in statement 1108, is formed by defining a two- 
byte constant of AL2(COM+@TUSTG). 
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Special Address of CCP Routine or Work Area: 

The entry must contain the hex value 80xx, where 
xx is a number used by CCP to signify which special 
address is to be referenced. Two such entries are 
used in this example. The symbol “PGM” has been 
equated to the value X‘8000', and the symbols 
"i#CC4TX” and “USI” have been generated by 

the macro $ETRC, and represent the numbers 

for the special addresses, respectively, of: 


a. $CC4TX -- the location to which you must 
branch at the completion of execution of 
your transient. 


b. The first byte of the user security information 


(from the module $CC4Z9) which you will 
use for checking the validity of the terminal's 
sign on data. 


The last entry in a Relocatable Address Table 
must be followed by a one-byte constant of hex 
FF (statement 1201). 


The Relocatable Address Table is used only at 

the beginning of a CCP run to establish the 
addresses used in your transient. Therefore, it 
does not have to be present in main storage during 
each execution of your transient. Because of this, 
the table may extend beyond the 512 bytes which 
is the maximum size of the executable portion of 
a transient. 


@ The first user transient to which control will be 
passed must be named $CC4YA. The first 
transient, (SCC4YA), may pass control to other 
user written transients, providing such addition- 
al transients are written and named according 
to established conventions, Any user-written 
transient receiving control after $CC4YA must 
be named such that the ist five characters of 
the name are $CC4Y. The sixth character of 
the name may be any character in the range 
B-Z. 


@ The last transient to be called, (or $CC4YA if it 

is the only one used), must transfer control to 
_ the transient area scheduler after setting the 

desired parameter value in location “TAXPRM”. 
The transfer of control is performed by 
branching to the CCP routine $CC4TX. Refer- 
ence sample program statements 1160, 1167, 
and 1176. 


@ The security data which was previously written 
in the modules $CC4Z9, will be available for 
reference by any user written transient in a 
user security work area. The leftmost byte of 
this work area will contain the first byte from 
the module $CC4Z9. The size of the work area 
and the size of $CC4Z9 is specified at Genera- 
tion by the operand ““LUSI" in the $ESEC 
statement. The address of the leftmost byte 
of this work area is available to the user’s 
transient by the value “P+ USI". See the sample 
sample program, statement 1129. 


Sample Program — Model 10 or Model 12 


Figure 7-2 is an example of a user sign-on security routine. 
The following notes explain the logic of the example: 


@ A total of six macros must be included in the source 
code. These macros produce equates used elsewhere in 
the program. Their names are as follqws: 


1.  $EEQU 
2.  $ECOM 
3. $ECPL 
4.  $ETUB 
5. $ETNT 
6. $ETRC 


These macros are available only on the CCP distribution 
disk cartridge (PIDOO1). Either copy these to your own 
source library or perform the macro processing step 

by loading $MPXDV from the distribution pack. 


® This sample program expects sign-on data in the form 
/ONKSSSSSS, where SSSSSS is the security code to be 
checked by $CC4YA. 


@ As used by this program, the security data found in 
$CC4Z9 must be of the following form: 


C,C,C,C,C,C,8,8,5,8,8,5,C,C,C,Co6,€,8,8,8,855,8 


1717079705110 22°22 2 222-22 2 2""° 


CC ... represents a six-character symbolic terminal name 
and SS ... represents a six-position security field. There 
should be as many sets of CC ... SS ... data residing in 
$CC4Z9 as there are terminals to be used by an assign- 
ment set for CCP. The intent of this data is to provide 
a vehicle by which $CC4YA can verify a unique six- 
character sign-on code for each terminal so specified by 
the symbolic terminal name. 


Statement 1129 loads XR2 with the address of the left- 
most byte of the security data residing in the security 
data work area. Statement 1151 compares the data 
entered from the terminal after the ‘ON’, and the data 

in the security data work area that is associated with one 
symbolic terminal name. 


Statement 1140 compares the symbolic terminal name 
to the names in the security data area. The program 
toops between statements 1137 and 1144 and is exited 
when the end of the security data area is reached 
(1139), or when the name of the terminal signing on 
compares equal to one in the security data area (1142). 


Statement 1160 puts ‘01’ in symbolic location 
'TAXPRM’. This value indicates that the security data 
for the selected terminal verified correctly. After 
control is returned to $CC4TX and given to the CCP 
transient $CC4SO, a message will be sent to the selected 
terminal which will indicate that the sign on was success- 
ful. 


Statement 1167 puts ‘FF’ in symbolic location 
‘TAXPRM‘. This value indicates that the security data 
for the selected terminal did not verify correctly. After 
control is returned to $CC4TX and given to the CCP 
transient $CC4SO; a message will be sent to the selected 
terminal which will say that the sign on was unsuccess- 
ful. 


Statement 1176 causes the control to be passed to the 
CCP transient $CC4SO. This is accomplished as follows: 


a. The field TAXTID (at relative location 6 in the 
transient) contains the displacement from the 
beginning of the transient of the first three bytes 
(location OA-OC of the transient) which address 
the transient $CC4SO. At CCP startup, the bytes 
at locations OB and OC are set to the disk address 
of that transient. 

b. The branch at statement 1176 gives control to the 
CCP Transient Area Scheduler, requesting it to 
pass control to the transient ($CC4SO) pointed 
to by the TAXTID field. 
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SCC4YA 


ERR LOC OBJECT CODE ADDR STMT 
1072 

0001 1074 

. 1075 

0001 1076 

0003 1077 

0005 1078 

0007 1079 

0008 1080 

OOOA 1081 

0005 1082 

1084 

0000 1086 

0000 0084 0001 1087 
1088 

1089 

1090 

0002 OE 0002 1091 
0003 O1 0003 1092 
1093 

0004 0000 0005 1094 
0006 000A 0007 1095 
a008 £206 0009 1097 
OOOA OL 000A 1098 
000B C3E2 000C 1099 
000D 58 000d 1100 
OOOE E8C1 OOOF 1101 
0010 03 0010 1102 
0011 1103 

1105 

1106 

0011 35 02 0038 1108 
0015 74 02 83 1109 
0018 6C 01 78 09 1110 
OO1C BD OA 05 111. 
OOLF F2 O01 41 1112 
0022 6E 01 78 05 1114 
0026 5F O1 78 6F 1115 
002A 75 02 76 1116 
002D 6C 09 79 00 1117 
1119 

1120 

0031 75 02 83 1122 
0034 85 02 21 1123 
0037 6 05 B1 05 1124 
1126 

1127 

0038 C2 02 0010 1129 
0O3F E2 02 05 1130 
1132 

1133 

1134 

1135 


SOURCE 
* 
TARLDA 
* 
TAJUMP 
TAID 
TAXPRM 
TAXTIO 
TAXCID 


TAXNCS 
TAXCLN 


YASO 


YAGO 


* 
* 


##0010 


##0020 


eee 


STATEMENT 


CCP TRANSIENT ROUTINE EQUATES 


EQu 1 OFFSET TO TRANSIENT 

CCP RELOCATION CONSTANTS 
EQU TARLDA DISPLACEMENT FOR JUMP OP + Q 
Equ TARLDO+2 OFFSET TO TRANSIENT PROGRAM 
EQu TATD+2 DISPLACEMENT TO PARM BYTES 
EQu TAXPRM42 OFFSET TO NCS VALUEA@ 
EQU TAXTID+) OFFSET TO TRANSYENY XCTL TABLE 
EQU TAXCID+2 OFFSET TO FIRST NCS PARAMETER 
EoQu 5 LENGTH OF AN XCTL TABLE ENTRY 


TRANSIENT PROLOG 


USING $CC4YAsXR1 DEFINE BASE REGISTER 


oc AL2(YASRLC-$CC4YA) OISPL OF CCP RELOCATE ADCONS 
NOTE, THESE BYTES ARE OVERLAID 
WITH A JUMP OP CODE AND X*87®* 
Q-BYTE BY $CC4TA 

oc ALL (YAGO-$CC4YA-3) OFFSET TQ FIRST INSTRUCTION 

oc XLLOLt TRANSIENT AREA [D+ USED BY 
TRANSTENT RELOCATION ROUTINE 

oc XL2°Or PARAMETER BYTES 

DC AL2(YASO-$CC4YA) DISPLACEMENT TO FIRST XCTLEE 

oC Cci2°sor SPECIFIES xCTL TO $CC4S0 

oc ALLL) N BYTE FOR DISK 

oc CL2*cst OISK C/S BYTES, SET BY CCP START 

boc CLitgse END OF XCTL TABLES FIELD 

oc CLatyat $CC4YA EYECATCHER CONSTANT 

oc XL1L°0O3° LEVEL NUMBER 

EQu * BEGINNING OF EXECUTABLE CODE 


CHECK THE LENGTH OF THE TERMINAL MESSAGE AND IF CORRECT 
THEN MOVE IT TO THE TRANSIENT DATA AREA. 


L C+aTUSTG »XR2 LOAD POINTER TO TUB 

ST YATUB(sXRLDeXR2 SAVE TUB POINTER 

MVC YAENOP(2 ,XR1) »TPRECAC,XR2) SAVE BEGINNING @ OF MSG. 
cLi TPEFFL(yXR2),10 TEST FOR CORRECT ENPUT LENGTH 
JNE YAERR JUMP TF NOT 

ALC VAENOP (29 XR1) » TPEFFLE » XR2) ADO LENGTH OF MESSAGE 

SLC VAENOP (29 XR1)» YAXONE (eXR1) DECREMENT POINTER 

L YAENDPC »XRL) »XR2 XR2 POINTS TO END OF INPUT 

MVC VAENDD(102XR 199005 XR2) MOVE SIGN ON DATA TO TRANSIENT 


MOVE THE 6 CHARACTER NAME OF THE TERMINAL ATTEMPTING 
TQ SIGN ON INTO AN AREA WITHIN THIS TRANSIENT. 


t VATUBUsXRLDSXR2 LOAD TUB POINTER 
L TUBTNT (¥XR2) 9XR2 LOAD ADDRESS OF TERMINAL NAME T. 
ave YANAME (6yXR1) ¢ TNTNAM(¢ XR2) MOVE TERMINAL NAME 


LOAD XR2 WITH THE ADDRESS OF THE LEFTMOST BYTE OF THE 
SECURITY DATA FOUND IN THE SECURITY DATA WORKAREA. 


LOAD POINTER TO SECURITY DATA 
BUMP POINTER 


tA 
LA 


P+US 1 XR2 
SUyXR2) o XRZ 


COMPARE THE 6 BYTE TERMINAL NAME PREVIOUSLY SAVED AND THE 
6 BYTE TERMINAL NAMES FOUND IN THE SECURITY DATA WORKAREA. 
KEEP COMPARING TILL A MATCH IS FOUND OR TELL THE END OF 
THE SECURITY DATA AREA IS REACHED 


Figure 7-2 (Part 1 of 2). Sample User Security Routine for Models 10 and 12 
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SCC4YA 
ER2 LOC OBJECT CODE ADDR STMT SOURCE STATEMENT 


0042 1137 YA0100 EQU * 


0042 8D 00 00 1138 cLi O1,XR2):0 
0045 F2 B81 18 1139 JE YAERR 
0048 6D 05 81 00 1140 CLC YANAME (69 XR1L) O09 XR2) 
1141 * 
p04C F2 81 O07 1142 JE YAOLLO 
O04F E2 02 OC 1143 LA 12% 9XR21_XR2 
0052 CO 87 0042 1144 ##0030 B YA0100 
1146 * 
1147 * 
1148 * 


0056 1150 YAO110 FQU * 


TEST FOR END OF DATA 

JUMP IF END HAS BEEN REACHED 
COMPARE NAME ENTERED & NAME IN 
SECURITY DATA AREA 

JUMP TF A MATCH IS FOUND 

STEP POINTER TO NEXT NAME FIELD 
TO TEST NEXT NAME 


COME HERE WHEN A POSITIVE MATCH HAS BEEN MADE SETWEEN THE 
TERMINAL NAME AND THE NAME IN THE SECURITY DATA AREA. 
NOW COMPARE THE SIGN ON DATA ASSOCIATED WITH THE TERMINAL NAME. 


COMPARE SIGN ON CODE FOR 
TERMINAL WHO'S NAME WAS JUST 
FOUND AND CODE IN SECURITY 


JUMP TO ERROR EXET IF CODE DOES 


PUT "01 IN PARAMETER 
TO €X1TT FROM THIS ‘TRANSIENT 


0056 90 05 06 79 1151 cLe 616)XR21,¥ AENDD(, XR) 
1152 * 
1153 * 
1154 * DATA FIELD 
OO5A F2 01 06 1155 JNE YAERR 
¢ 1156 * NOT COMPARE 
1158 * THE SIGN ON DATA HAS COMPARED OK, SO PUT A X*O1* IN *TAXPRM!, 
0050 YC OL 05 1160 MVI TAXPRMT,XR1D, YAEQUL 
0060 F2 87 03 i161 J YAOUT 
1163 * THE SIGN ON DATA OLD NOT COMPARE CORRECTLY?» 
1164 * SO PUT A X*FFE IN *TAXPRMS. 


0063 1166 YAERR EQU * 


PUT *FFY IN PARAMETER 

THIS SIGNIFLIES THAT THERE WAS 
AN ERROR IN THE SIGN ON 
VALIDATION . 


0063 7C FF 05 1167 MVI TAXPRM( »XRL) + YAE QUE 
1168 * 
1169 * 
1170 * 
1172 * COME HERE TO EXIT FROM THIS TRANSTENT 


0066 1174 YAOUT FQU * 


0066 3A CO 0500 1175 ##0260 SBN C+S$CPWK+SCPFLG pSCPTT+S$CPFR 
006A CO 97 0009 1176 ##0270 BC P+H#CC4TXSBR9O7 TO XCTL 
1178 * CONSTANTS AND DATA AREAS 
OO6E 0001 OO6F 1180 YAXONE DC XL2*01° CONSTANT 
0070 0000000000000000 0079 1181 YAFNDD DC xXL1O'O* INPUT DATA GOES HERE 
0078 9000 1181 
007A 0000 0078 1182 YAENDP OC xL2¢0° LENGTH OF MESSAGE 
007C 000000000000 0081 1183 YANAME DC XL6t 08 TERMINAL NAME GOES HERE 
0082 0090 0083 1184 VYATUB DC xL2*O* SAVE AREA FOR TUB POINTER 


OOFF 1186 YAEQUF EQU X¢FFP 
0001 1187 YAEQUL EQU 1 


$000 1188 PGMN EQU x*8000°* 

C000 1189 COM EQU x*C€000* 

0000 1190 C . €EQU SCC4YA 

0000 1191 P £QU SCC4YA 

1193 * RELOCATION ADDRESS TABLE 

0084 1195 YA@RLC EQU * 
0084 CO3B 0085 1196 aa0010 DC AL2(COM+ATUSTG) 
0086 BOLD 0087 1197 280020 DC AL2(PGMtUST) 
0088 0042 9089 1198 320030 DC AL2(YA0100~P) 
008A C500 008B 1199 330260 DC AL2(COM+$C PWK+$C PFLG) 
908c 8009 0080 1200 320270 OC AL2( PGMFACC4TX) 
OOB8E FF OOBE 1201 pc XLL'FF* 

0000 1202. END SCC4YA 

TOTAL STATEMENTS IN ERROR IN THIS ASSEMBLY = 0 


Figure 7-2 (Part 2 of 2). Sample User Security Routine for Models 10 and 12 
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PROGRAMMING A USER SECURITY ROUTINE — 
MODEL 15 


The user of CCP may, if he chooses, write his own terminal 
sign on security routines rather than use the CCP password 
facility supplied with his system. To implement and use 
such routines, the following must be considered. 


This option must be selected at generation time by the 
“SECURE-USER” operand of the $ESEC statement. 


The security data which will be used at terminal sign 
on time by the security routines must have been 
previously written to the security module $CC4Z9 
by User Security Data Program, $CCPAU (see CCP 
System Reference Manual). 


The user security routines must be written in Basic 
Assembler Language (or an equivalent machine-level 
language} and must be structured such that they 
comprise three basic parts (statement numbers refer 
to the sample program, Figure 7-3): 


1. System equates. They provide the necessary 
offsets and pointers to various system tables, 
as well as other common equates. 


2. The transient prologue and equates. The function 
of this code is to provide the following: 


a. JUMP instruction to the start of executable 
code (statement 8). 

b. A two-byte field of hex 0000 to permit the 
passing of a parameter from this transient 
to another (statement 10). 

c. A two-byte address pointing to the third 
character past the ID of the transient to 
be called next (statement 11). 


d. The two-character !D of the transient to be 
called next, consisting of the last two 
characters of the module name (statement 
12). 

e. Three bytes for disk control which are used 
when this transient is read from disk (state- 
ment 12). A one-character delimiter ($) 
and the two-byte ID of this transient 
follow (statement 13). 
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The main body of code, which in this example begins 
with statement 836 and ends with statement 909. 
This sample code will: determine the length of, 
and move the sign-on data to an area within this 
transient; determine which terminal is attempting 
to sign on and then verify the sign-on data for that 
terminal, as found in the user security work area; 
pass the result of the verification to the CCP sign- 
on transient, $CC4SO, by setting a value in 
“TAXPRM"” prior to exiting from this transient. 
The ““‘TAXPRM" field of any CCP transient (at 
relative locations 4 and 5 of the transient) is the 
field in which one transient passes information to 
another. The total length of parts 2 and 3 cannot 
exceed hex length 1FF. 


@ The first user transient to which control will be passed 


must be named $CC4YA. The first transient, 
($CC4YA), may pass contro! to other user written 
transients, providing such additional transients are 
written and named according to established conventions. 
Any user-written transient receiving control after 
$CC4YA must be named such that the 1st five characters 
of the name are $CC4Y. The sixth character of the 
name may be any character in the range B-Z. 


The last transient to be called, (or $CC4YA if it is the 
only one used), must transfer control to the transient 
area scheduler after setting the desired parameter value 
in location “TAXPRM”. The transfer of control is 
performed by branching to the CCP routine $CC4TX. 
Reference sample program statements 883, 890, and 
898. 


The security data which was previously written in the 
modules $CC4Z9, will be available for reference by any 
user-written transient in a user security work area. The 
leftmost byte of this work area will contain the first 
byte from the module $CC4Z9. The size of the work 
area and the size of $CC4Z9 is specified at Generation 
by the operand ““LUSI” in the $ESEC statement. The 
address of the leftmost byte of this work area is available 
to the user’s transient by the value @USECW. See the 
sample program, statement 852, 


Sample Program — Model 15 


Figure 7-3 is an example of a user sign-on security routine. 
The following notes explain the logic of the example: 


e A total of five macros must be included in the source 
code. These macros produce equates used elsewhere in 
the program. Their names are as follows: 


1. $EEQU 
2. $ECOM 
3. $ECPL 
4.  $ETUB 
5. $ETNT 


These macros are available only on the CCP distribution 
disk cartridge (P1ID001). Either copy these to your 
own source library or perform the macro processing 
step by loading $MPXDV from the distribution pack. 


®@ This sample program expects sign-on data in the form 
/ON#SSSSSS, where SSSSSS is the security code to be 
checked by $CC4YA. 


@ As used by this program, the security data found in 
$CC4Z9 must be of the following form: 


C, 0, C, C1 Cy Cy S; $1 $1 $1 $1 G1 Cy Cz C2 Cz C2 C2 S$. $2 SS. $2 .. . 00 


CC... represents a six-character symbolic terminal 
name and SS... represents a six-position security field. 
There should be as many sets of CC...SS... data 
residing in $CC4Z9 as there are terminals to be used by 
an assignment set for CCP. The intent of this data is to 
provide a vehicle by which $CC4YA can verify a unique 
six-character sign-on code for each terminal so specified 
by the symbolic terminal name. 
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@ Statement 852 loads XR2 with the address of the left- ®@ Statement 890 puts ‘FF’ in symbolic location 
most byte of the security data residing in the security ‘TAXPRM’. This value indicates that the security data 
data work area. Statement 874 compares the data for the selected terminal did not verify correctly. After 
entered from the terminal after the ‘ON’, and the data control is returned to $CC4TX and given to the CCP 
in the security data work area that is associated with transient $CC4SO, a message will be sent to the selected 
one symbolic terminal name. terminal which will say that the sign on was un- 

successful. 

Statement 863 compares the symbolic terminal name 
to the names in the security data area. The program © Statement 898 causes the control to be passed to the 


loops between statements 860 and 867 and is exited 


CCP transient $CC4SO. This is accomplished as follows: 


when the end of the security data area is reached (862), 
or when the name of the terminal signing on compares a. 
equal to one in the security data area (865). 


The field TAXTID (at relative location 6 in the 
transient) contains the displacement from the 
beginning of the transient of the first three bytes 
(location OA-OC of the transient) which address 
the transient $CC4SO. At CCP startup, the bytes 
at locations OB and OC are set to the disk address 
of that transient. 


@ Statement 883 puts ‘01’ in symbolic location 
‘TAXPRM’. This value indicates that the security data 
for the selected terminal verified correctly. After 
control is returned to $CC4TX and given to the CCP 


transient $CC4SO, a message will be sent to the selected b. The branch at statement 898 gives control to the 
terminal which will indicate that the sign on was CCP Transient Area Scheduler, requesting it to 
successful. pass control to the transient ($CC4SO) pointed 
to by the TAXTID field. 
$CC4YA 


ERR LOC OBJECT CODE ADDR STMT SOURCE STATEMENT 


2 * $EBEG N-Y¥A,X1-SO+TID-1 
4000 3 $CC4YA START 16384 TRANS TENT START DEFINITION 
4000 4 $CC4$$ EQU * $CC4$$ DEFINITION 
5 LEVEL 02 
6 RLO N 
7 
7 : 
4000 F2 87 OD 8 J YAGO BYPASS PHASE ID'Sy C/S*S 
4000 9 USING $CC4YA,1 DEFINE BASE ON TRANSIENT ENTRY 
4003 0000 4004 10 TAXPRM OC XL2*0000° TRANSIENT COMMUNTCATION AREA 
4005 4008 4006 11 TAXTIO OC AL2(VASO) INITIALLY 1ST CSN OTSPLACEMENT 
4007 E£206404040 4008 12 YAS oc CL5*SO . PHASE ID, SPACE FOR C/S/N 
400C 5BE8C1 400E 13 oc CL3"$YA! EYECATCHER CONSTANT 
400F 02 400F 14 oc XL1'02¢ RELEASE LEVEL 
4010 15 YAGO EQU * END OF $EBEG CONSTANTS 
833 * COME CHECK THE LENGTH OF THE TERMINAL MESSAGE AND IF CORRECT 
834 * THEN MOVE IT TO THE TRANSIENT DATA AREA. 
835 
4010 OD 00 44€6 405C 836 cLC $CPEFL,YATEN TEST FOR CORRECT INPUT LENGTH 
4016 F2 01 38 837 JNE YAERR JUMP TF NOT 
838 
4019 35 02 4468 839 Ll $CPRCAyXR2 XR2 POINTS TO END OF INPUT 
401D 6C 05 62 09 840 uve YAENDO(69XR19 9909 XR2) MOVE SIGN ON DATA TO TRANSIENT 
841 
842 * MOVE THE 6 CHARACTER NAME OF THE TERMINAL ATTEMPTING 
843 * TO SIGN ON INTO’ AN AREA WITHIN THIS TRANSIENT. 
844 
4021 35 02 4467 845 L @TUSTGsXR2 LOAD TUB POINTER 
4025 BS 02 17 846 L TUBTNT (4 XR2) eXR2 LOAD ADORESS OF TERMINAL NAME T. 
4028 6C 05 68 05 847 MVE YANAME (6¢XR21) 9 TNTNAM(,XR2} MOVE TERMINAL NAME 
848 
849 * LOAD XR2 WITH THE ADDRESS OF THE LEFTMOST BYTE OF THE 
850 * SECURITY DATA FOUND IN THE SECURTTY DATA WORKAREA. 
851 


Figure 7-3 (Part 1 of 2). Sampte User Security Routine for Model 15 
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SCC4YA 


ERR LOC OBJECT CODE 
402C 35 02 4411 
4030 £2 02 05 
4033 
4033 BD 00 00 
4036 F2 81 1B 
4039 6D 05 68 00 
4030 F2 81 07 
4040 E2 02 OC 
4043 CO 87 4033 
4047 
4047 9D 05 06 62 
4048 F2 01 06 
404E 7C 01 04 
4051 F2 87 03 
4054 
4054 70 FF 04 
4057 
4057 35 10 4403 
4058 000A 405C 
4050 000000000000 4062 
4063 000000000000 4068 
OOFF 
0001 
41FC 
4000 


852 
853 
854 
855 
856 
857 
858 
859 
860 
861 
862 
863 
864 
865 
866 
867 
868 
869 
870 
871 
872 
873 
874 
875 
876 
877 
878 
879 
880 
881 
862 
883 
884 
885 
886 
887 
888 
889 
890. 
891 
892 
893 
894 
895 
896 
897 
898 
899 
900 
901 
902. 
903 
904 
905 
906: 
907 
908 
909 


eee Ht 


YA0100 


* 

% 

* 
YAO110 


* 
* 
* 


YAERR 


et He 


YAOUT 


x 


YATEN 
YAENODO 
VANAME 


YAEQUE 
VAEQUI 


ADOR STMT SOURCE STATEMENT 


L DUSECWsXR2 LOAD POINTER TO SECURITY DATA 
LA BSC yXR20_ XRZ BUMP POINTER 


COMPARE THE 6 BYTE TERMINAL NAME PREVIOUSLY SAVED ANO THE 
6 BYTE TERMINAL NAMES FOUND IN THE SECURITY DATA WORKAREA. 
KEEP COMPARING TILL A MATCH IS FOUND OR TILL THE ENO OF 
THE SECURITY DATA AREA 1S REACHED. 


EQu * 

cli O€sXR21 +0 TEST FOT END OF DATA 

JE YAERR JUMP TF END HAS BEEN REACHED 

cc VANAME COeXR1IF +O 2 XR2} COMPARE NAME ENTERED & NAME IN 
SECURITY DATA AREA 

JE YAO1IO JUMP TF A MATCH 1S FOUND 

LA 120,XR2¥ yXR2 STEP POINTER TO NEXT NAME FIELD 

8 YA0100 TO TEST THE NEXT NAME 


COME HERE WHEN A POSITIVE MATCH HAS BEEN MADE BETWEEN THE 
TERMINAL NAME ANDO THE NAME IN THE SECURITY DATA AREA. 
NOW COMPARE THE SIGN ON DATA ASSOCIATED WITH THE TERMINAL NAME. 


EQU * 
cite 6 (69XR2 I 9 YAENDD(, XR1} COMPARE SIGN ON CODE FOR 
; TERMINAL WHO'S NAME JUST 
FOUND AND CODE IN SECURITY 
DATA FIELD 
JNE ¥AERR JUMP TO ERROR EXIT IF CODE DOES 


NOT COMPARE 
THE SIGN ON DATA HAS COMPARED OK, SO PUT A X01" IN *TAXPRM!. 


MVT TAXPRM(,XRED 9 YAEQUL PUT "01" IN PARAMETER 
J YAOUT TO EXIT FROM THIS TRANATENT 


THE SIGN ON DATA DID NOT COMPARE CORRECTLY, 

SO PUT A X*FEP EN 'TAXPRME. 

EQU * 

MVI TAXPRM( > XR1) » YAEQUF PUT ©FFt IN PARAMETER 
THIS SIGNIFIES THAT THERE WAS 
AN ERROR IN THE SIGN ON 
VALIDATION. 

COME HERE TO EXIT FROM THIS TRANS IENT 


EQU * 
L @CC4 TX» TAR TO XCTL 


CONSTANTS AND DATA AREAS 
o¢ XL2* 000A" 


oc. xceror INPUT DATA GOES HERE 

oc XL6*O# TERMINAL NAME GOES HERE 
EQU XeFFS 

E€QU 1 


ORG $CC4YA+508 
END $CC4YA 


Note: The following names, used in this figure, are defined 
in macros; the macros are not shown in this figure: 


Name 


$CPEFL. 
$SCPRCA 
@TUSTG 
@CC4TX 
TUBTNT 
TNTNAM 


Macro Defined in 


$ECOM 
$ECOM 
$ECOM 
$ECOM 
$ETUB 
$ETENT 


Figure: 7-3: (Part 2 of 2). Sample User Security Routine for Model 15 
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GENERAL INFORMATION 


The 3270 Display Format Facility is an optional feature 
of the Communications Control Program (CCP). This 
facility allows programs to control printer and display 
formats on the IBM 3270 Information Display System 
with a minimum of coding. Instead of requiring a special 
assembler language subroutine, programs can interface 
with the 3270 in a high level language (RPG Il, COBOL, or 
FORTRAN IV). For those programs written in assembler 
language, CCP provides interfacing macros that can be used 
with DFF (see Chapter 7. Basic Assembler Programming 
for CCP). 


Chapter 8. 3270 Display Format Facility (DFF) 


Overview 
The 3270 Display Format Facility offers: 


@ An easy way to define printer and display formats (use 
special form for offline generation). 


@ Formats that are program independent (stored on disk, 
not in the application program). 


@ Formats that can be used by several programs con- 
currently (the format remains unmodified on disk, 
therefore can be used by several programs). 

@ Aneasy way to handle data (all data is arranged in fields). 

® Two ways of supplying data—at generation time (as part 
of the field definition) or during execution time (by the 


application program). 


@ The capability to change the characteristics or 
contents of a field on the display screen. 


@ Testing formats offline before writing the application 
program. 


@ Testing a terminal without writing a teleprocessing 
program. 
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Prerequisite tnformation 
In order to fully utilize DFF, it is essential that you have 
a basic understanding of the concepts and operation of the 


IBM 3270 Display system. This includes understanding 
the uses of: 


@ Write Control Character (WCC) 

® New Line, End of Message, and Forms Feed (NL,EM,FF) 
® Selector Pen 

® Operator Identification Card Reader 

® Copy Control Character (CCC) 

® Attention Identification (AID) 

@ Modified Data Tag (MDT) 

® Keyboard keys and functions 

For information on any of the above, refer to /BM 3270 


Information Display System Component Description, 
GA27-2749. 
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DFF Routines 


The Display Format Facility provides four routines — the 
Display Format Generator, the Printer Format Generator, 
the Display Format Control, and the Display Format Test: 


1. The Display Format Generator routine runs offline; 
that is, it does not run under control of CCP. The 
display format generated by this routine is used by 
the Display Format Control Routine (DFCR), which 
does run under CCP. The Display Format Generator 
can run in either level of a DPF system, and it can 
run while CCP is executing. If DFGR is running 
while CCP is executing in the other level, the format 
being processed cannot be placed on the pack from 
which CCP was loaded; if this is attempted, an EO 
F PP halt occurs. 


2. The Printer Format Generator runs offline; that is, 


it does not run under control of CCP, although the 
printer format it generates is used by the Display 
Format Control Routine (DFCR), which does run 
under CCP. The Printer Format Generator can run 

in either level of a DPF system, and it can run while 
CCP is running. !f PFGR is running while CCP is 
executing in the other level, the format being processed 
cannot be placed on the pack from which CCP was 
loaded; if this is attempted, an EO F PP halt occurs. 


3. The Display Format Control routine helps the transfer 


of data to and from the 3270 terminal. This routine 
does run under control of CCP. 


4. The Display Format test routine runs offline; that 


is, it does not run under control of CCP. This routine 
is used as a development too! for designing and testing 
printer and display formats. 
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Two forms are used in preparing materiai for either the printer or the dispiay format generators: the 

printer/display layout sheet, and either the printer format specifications sheet (for PFGR) or the dis- 

FS seen As play format specifications sheet (for DFGR). The following describes the procedure used to generate 
| a format. Descriptions applicable only to a particular routine are contained solely within its column; 


iNPUT 


| descriptions applicable to both routines span both columns. 
| 
| Printer Format Generator Display Format Generator 
Format | i — . ‘ : 
See ie Arrange the fields on the layout sheet just as they are to appear on the form or display. 
Specifications | 
q If the format has more than 33 lines, more than P include all fields that can be written to and/or 
one sheet is needed. [received from the 3270. 


ces 


Source 


Use the completed layout sheet as a guide in completing the two parts of the format specifications 
Shit — sheet (control and field definition forms). Provide for each field the name, type, location, associated 
|_data, and other needed information. 






[ Transfer the information from the specifications sheet to the system input device or to the source 
a [library using $MAINT. 


—_— —{System input records or source library statements are read by the format generator routine. 





Format 








Specifications The format generator routine: / "The format generator routine: 
Log and nN Na 2 ee toe ee _| @ Produces a printout of the specifications forms. | @ Produces a printout of the specification forms. 
Diagnostics | @ Analyzes specifications for errors. ®@ Analyzes specifications for errors. 
Z L® _Logs diagnostic error messages. e _Logs diagnostic error messages. 
oa —{The formats are cataloged into an object library under a user-designated name. 
| [The format is built in two parts: 
| | ® Field descriptor table containing the symbolic field names and is used to identify those fields for 


7 which data must be supplied in the user’s output record area, and to support overrides to fields 
within the format. 
[e Complete data stream including control characters. 


iF he printed information includes: [ The printed information includes: 
@ Information used by the application program: @® Information used by the application program: 
| — Required output data and the order of — Required output data and the order of 
output data fields that must be provided output data fields that must be provided 

| in the user’s output record area in the user's output record area 

eae os + @ Information used in preparing the CCP assign- — Input data and the order of input data: 
T ment set under which the application pro- fields as they are passed to the applica- 
gram will execute: tion program in the user’s input record 


See ae 
| 
| 
| 
J 
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| — The decimal length of the field descriptor area 
table @ Information used in preparing the CCP assign- 
| — The decimal length of the output data ment set under which the application pro- 





Input and 
Output Record 
Area Formats 


L ___ stream 


gram will execute: 

— The decimal length of the field descriptor 
table 

— The decimal length of the 3270 output 
data stream 

— The decimal length of the 3270 input data 

‘stream 







(—---- 


— 


Modifiers to existing operations and three additional oper- 
ations (Copy, Put Override, and Erase) support the 3270 
functions. The Copy operation is used to transfer a format 
between devices attached to the same 3271 control unit. The 
Put Override operation is used to (1) change the type, repo- 
sition the cursor, modify the data content (or any combi- 
nation of these) of any field or fields defined in the format, 
and/or (2) request input from only selected fields within the 
display format. The Erase operation fills the data positions 
of all unprotected fields (input field types 1, 2, 3, 4 and out- 


put/input field types 1, 2, 3, 4) with null (hex 00) characters. 


In all cases, additional entries in the CCP application 
program’s output record area are required. For example, 
when requesting that a format be written to a 3270, the 
name of the format must be given in the record area. In 
the input record area, allowance must be made for the 
AID character. 


Requests for display or printer format services use the 
same application interface as do other CCP requests; the 
application program passes a parameter list and a record 
area. 


It is essential that the printer/display layout and specifica- 
tion sheets be completed accurately so that the control 
routine can operate exactly as intended. To do this, you 
need a working knowledge of such things as the field con- 
cept of handling data and the characteristics of each type 
of field within each of the field classes. You need to know 
how to determine /engths of fields, what field attributes 
are and how the cursor is positioned. 


FIELD CONCEPTS 

Definition 

All 3270 display information is treated as a set of fields 
within a record rather than as a string of data. Each field 
has certain characteristics associated with it—such as whether 
it is alphameric or numeric. Field characteristics are 


defined by type and class. 


Class describes whether the field is output, input, output/ 
input, or selector pen detectable. 


Type describes what group of characteristics are associated 
with the field. 
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Field Classes 


The field class is selected at format generation time by the 
application programmer when using the Display Format 
Generator. When using the Printer Format Generator, the 
field class is assumed to be output. The field class deter- 
mines what the terminal operator can or cannot do with 
that field (see Figure 8-1). For prompting or displaying 
messages to the terminal operator, an output class would 

be used. {f data for a field is to be provided by the terminal 
operator, an input class would be used. If data for a field 

is to be initially provided by the application program but 
allowed to be changed (using the keyboard) by the terminal 
operator, an output/input class would be used. Lastly, a 
field class has been provided solely in support of the selector 
pen. 


A description of the four field classes follows: 


® Output field—contains data that cannot be changed 
by the terminal operator. The data for the field is 
supplied either during format generation or during 
execution of the application program. 


@ input field—is an area reserved for keyboard entry; data 
for the field is entered by the terminal operator. 


® Output/Input field—contains data which has been 
supplied either during format generation or during 
execution of the application program. This data can be 
changed by the terminal operator using the keyboard. 


® Selector Pen Detectable (SPD) field—allows the termi- 
nal operator to select fields by using the selector pen. 


All classes of fields may be used within the same display 
except when the SPD field is used as an attention field (see 
Attention Fields). 


FIELD CLASSES 


SELECTOR PEN ‘ 


OUTPUT INPUT OUTPUT/INPUT DETECTABLE (SPD} 
TYPES — 








Designator Character : 


MODIFIED DATA TAG — ON 
| 


(This information also appears on the reverse side of the display layout sheet.) 










CHARACTER- 
ISTICS : 








Note: Shaded squares indicate that these fields are not intended to be used as detectable fields. To prevent 
accidental detection of such a field, users should avoid using one of the characters 6, ?, >, or null (X‘00’) 
as the first character in the field. 


Figure 8-1. Field Classes; Types Within Classes; and Characteristics Associated With Each Type 


The field class selected determines, to some extent, the modified data tag may be set ON by (1) a keyboard input 
characteristics of a field. Differences in characteristics to the field, (2) a selector pen detection in the field, 
by class are: (3) a magnetic card read-in operation, (4) application 
program control, or (5) using the ERASE EOF key. The 
e Protected or Unprotected — A field is protected if the modified data tag can be set OFF by (1) a selector pen 
terminal operator cannot use the keyboard or operate the detection in the field, (2) application program control, 
identification card reader to enter, modify, or erase data or (3) use of the ERASE INPUT key. 
within that field. Output and selector pen detectable 
fields are protected. Input field types 5 and 6 and When data for a particular field /s not received from the 
output/input field types'5-8 are protected. terminal, blanks are passed to the application program. 
@ Alphameric or Numeric — All output and selector pen When data for a field is received from the terminal, it is 
detectable fields are alphameric. ./Input and output/input passed on to the application program. 
fields may be either alphameric or numeric (see Field 
Types). 


@ Modified Data Tag ON or OFF — The modified data tag 
associated with each field causes the data from that field 
to be returned (MDT-ON) or not returned (MDT-OFF) 
during an input operation from the terminal. The 
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Setting the modified data tag conditions what is received 
as input from the terminal and passed to the application 
program. Therefore, field classes affected by setting the 
modified data tag are: input, output/input, and selector 
pen detectable fields. For input fields, data will be received 
from the terminal only if the terminal operator has per- 
formed a keyboard input, ERASE EOF, or a magnetic 
card read-in operation. For output/input fields, data will 
normally be received from the terminal (see Outout/Input 
Field Types for a discussion on output/input fields that 
have the MDT set to OFF, types 5 and 6). The terminal 
operator should not use the ERASE INPUT key with an 
output/input field. For setector pen detectable fields, 
data may or may not be received from the terminal, even 
though the field type selected (see Field Types) required 
that the modified data tag be set to ON initially. Detec- 
tion by the terminal operator, on a selector pen detectable 
field can set the MDT from ON to OFF or from OFF to 
ON. 


Field Types 


Within a field class, the field type selected also determines 
characteristics of a field (see Figure 8-1). The type is 
selected at format generation time by the application 
programmer when using the Display Format Generator. 
When the Printer Format Generator is used, the field type 
does not apply. 


Choice of characteristics by type are: 


@ Alphameric or Numeric — \nput and Output/input 
fields may be specified as either alphameric or numeric. 


@ Moditied Data Tag ON or OFF — An output/input field 
would normally have its modified data tag set to ON. 
For special use of an output/input field with its modified 
data tag set to OFF, refer to types 5 and 6 under 
Output/Input Field Types. 


Aselector pen detectable field may be specified with its 
modified data tag set to either ON or OFF. The initial 
setting can be changed by the terminal operator using the 
selector pen. 


®@ Intensity of Normal, High, or OFF (nondisplay) -- 
Nondisplay fields are not visible on the screen or printed 
on the printer. Field types are also provided which allow 
a field to be displayed with normal intensity or high 
intensity. 
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With the 3270 terminal, both the application programmer 
and the terminal operator should be aware that a// 
high-intensity fields, regardless of class, have the potential 
of being detectable by the selector pen (see the note on 
Figure 8-1). To prevent an erroneous detection ona 
high-intensity non-SPD field, the first character in the 
field should not be a blank, null, question mark, or 
greater than character. This caution must be exercised 

by the application programmer when providing data 

for an output or output/input field class at format 
generation time or application program execution time. 
This condition can also be caused by the terminal 


- operator when keying data or when using the cursor 


positioning keys. 


If an erroneous detection on a high-intensity non-SPD 
field occurs, the interpretation of the data passed to 
the application program is the responsibility of the 
user (the designator character will not be separated 
from the data, and the data will be handled as usual 
for alphameric and numeric fields). Following is a 
breakdown of characteristics of each type under each 
class, 


Output Field Types 


i [] 


Type 










Protected Protected Protected 
Alphameric Alphameric Alphameric 
MDT-OFF MDT-OFF MDT-OFF 


Characteristics 


Normal intensity High intensity Nondisplay 


Nondetectable: Detectable Nondetectable 


All types of output fields have the characteristics of being 
protected, alphameric with the modified data tag set to 
OFF, 


On input operations, data from output fields will not be 
passed to the application program. 


The data for output fields is always handled as an alpha- 
meric value. Data will be displayed exactly as presented, © 
whether supplied at format generation time or during 
execution time by the application program. If there are 
numeric values in the field, the application programmer 

is responsible for such editing of data as insertion of 
decimal points and other characters to properly display 
positive and negative quantities. 


Type 1 (normal intensity) and type 2 (high intensity) \ 
output fields are used where data is to remain displayed. 

For example, headings and labels would appear on the screen 
and would not be subject to change by the terminal 
operator. Type 2 is indicated as being detectable only 
because it also has the high intensity characteristic; it is 

not intended that the selector pen be used. See the dis- 
cussion of intensity under Field Types. 


A type 5 field with the nondisplay characteristic can be 
changed using the override facility at execution time to 
become a type 1 or type 2 with the corresponding 
intensity characteristic, This is used to display appropriate 
error messages or comments as they are needed (see Put 
Override). 
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Input Field Types 


Typel 









Unprotected 


Alphameric Alphameric Numeric 


MDT-OFF MDT-OFF MDT-OFF 


Normal High 
intensity intensity 


Unprotected 


Normal 


Non- 
detectable 





Non- Detectable 
detectable 


All input fields have the modified data tag set to OFF. 


Type 1 is the normal alphameric input field. 


Type 2 allows for accenting an alphameric field (high 
intensity), 


Type 3 is the normal numeric input field. 


Type 4 allows for accenting a numeric field (high intensity). 


A field specified as type 5 at format generation time can 
be changed using the override facility at execution time 
to become a type 7 with normal intensity or type 2 with- 
high intensity. 


A field specified as type 6 at format generation time can 

be changed using the override facility at execution time 

to become a type 3 with normal intensity or type 4 with 
high intensity. Note that type 5 is alphameric while type 6 
is numeric. 
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Unprotected Unprotected 


MDT-OFF 


High Non- Non- 
intensity intensity display display 





Detectable Non- Non- 
detectable detectable 


Protected 


MDT-OFF MDT-OFF 
Non- Non- 
display display 
Non- Non- 
detectable detectable 


Types 2 and 4 are indicated as being detectable only because 
they also have the high intensity characteristic; it is not in- 
tended that the selector pen be used. See the discussion 

of intensity under Field Types. 





He 


MDT-OFF MDT-OFF 





Type 7 input field is intended primarily for use as a security/ 
authorization field. Data can be entered from the keyboard 
without displaying the data on the screen. Handling of 

the security/authorization data is left to the user. This 

field type may be changed using the override facility at 
execution time to a type 1, 2, or 5. 


Type 8 input field is intended primarily for use as a 
security/authorization field. Data can be entered from 
the keyboard without displaying the data on the screen. 
Handling of the security/authorization data is left to the 
user. This field type may be changed using the override 
facility at execution time to a type 3, 4, or 6. Note that 
type 7 is alphameric while type 8 is numeric. 


Output/Input Field Types 


Type 



















Unprotected Unprotected Unprotected 


Alphameric Numeric 


Alphameric 


MDT-ON MDT-ON MDT-ON 


Normal 
intensity 


Normal 
intensity 


High 
intensity 


Non- 
detectable 


Non- Detectable 


detectable 





The word Output in the class designation indicates that the 
field contains data which has been supplied at generation 
time (see Field Definition Form) or by the application 
program at execution time. The /nput indicates that the 
data may be changed by the terminal operator using the 
keyboard. 


An example of using the output/input field would be in 
checking a “SHIP TO” address. The address is placed on 
the screen, is checked to see that it is still correct, is 
changed if necessary, and is returned to the application 
program. 


Type 1 is the normal alphameric output/input field. 


Type 2 allows for accenting an alphameric field in the 
display (high intensity). 


Type 3 is the normal numeric output/input field. 


Type 4 allows for accenting a numeric field (high intensity). 


Types 2 ancl 4 are indicated as being detectable only 
because they also have the high intensity characteristic; 
it is not intended that the selector pen be used. See the 
discussion of intensity under Field Types. 





7 


Protected 
Alphameric 


MDT-ON 


[2] 
[2] 
[-] 










Unprotected 


Alphameric 


MDT-OFF 


Non- 
display 


Non- 
detectable 


Alphameric 


MDT-ON 







Numeric 


MDT-ON 


MDT-OFF 
‘Non- 
display 
Non- 
detectable 


A field specified as type 5 at format generation time can be 
changed using the override facility at execution time to 
become a type 1 with normal intensity or type 2 with 

high intensity. 


High Non- 

intensity display 
Non- 
detectable 


Normal 
intensity 


Non- 
detectable 


Detectable 





A field specified as type 6 at format generation time can 
be changed using the override facility at execution time 
to become a type 3 with normal intensity or type 4 with 
high intensity. Note that type 5 is alphameric while 
type 6 is numeric. 


A field specified as type 7 or 8 at format generation time can 
be changed using the override facility at execution time 

to become a type 1 with normal intensity, a type 2 with 
high intensity, or a type 5 nondisplay. Note that types 1 
and 2 have modified data tag on while type 5 has modified 
data tag off. 


Type 3, 4, or 6 fields cannot be overridden to types 7 
or 8. Also, type 7 and 8 fields are not interchangeable 
by means of the Put Override facility. 


Note: You will be unable to copy a display using the 
Copy operation if the field whose data begins in row 
1 column 2 is a type 5, 7, or 8 output/input field. 
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Selector Pen Detectable Field (SPD) Types 






















































rt OH Ho f 
Designator ? ? > > ? b b 
Protected Protected Protected Protected Protected Protected Protected 
Alphameric Alphameric Alphameric Alphameric Alphameric Alphameric Alphameric 
Normal Normal Normal High 
intensity intensity intensity intensity display intensity intensity 
= detectable 





Selectio 





As indicated, SPD fields are selection fields, nondisplay, or 
attention fields. 


Selection: For fields specified as types 1, 2, 3, or 4 at 
format generation time, the designator character is a visible 
indicator on the screen and indicates whether the MDT is 
off or on. The designator is automatically assigned during 
generation of the display format based on type specified. 
Therefore, the user should not include the designator as 
part of the data for an SPD field. When sensed with a 
selector pen, the designator changes as shown below: 


Designator Selector Pen Detection Results 

? (type 1) Changes to > (type 3) and MDT 
set to ON 

? (type 2) Changes to > (type 4) and MDT 
set to ON ; 

> (type 3) Changes to ? (type 1) and MDT 
set to OFF 

> (type 4) Changes to ? (type 2) and MDT 
set to OFF 
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Nondisplay: Since type 5 is a nondetectable field, it 
cannot be changed by the use of the selector pen. A field 
specified as type 5 at format generation time can, however, 
be changed using the override facility at execution time. 
All SPD types are interchangeable by using the Put Over- 
rides facility. 


Attention: \f an attention field (type 6 or 7) is present, 
only output and SPD fields can be contained in the same 
display format. Use of the selector pen to generate I/O 
pending will result in transmission of only the addresses 
of fields in which the modified data tag was set on (field 
data not included). Users who wish to combine SPD 
field input with keyed input must use the keyboard 
(ENTER or PF keys) to cause the data to be sent to the 
application program rather than using SPD attention. 


PLANNING THE PRINTER/DISPLAY LAYOUT 


Before working with the printer/display layout sheet (Fig- 
ure 8-2), the application programmer must be aware of the 
space requirements for each field class. The fields, as 
designed on the printer or display layout form, will have a 
direct correspondence with the information as it appears 
in the buffer of the 3270 screen or printer. 


LEGEND: 





Defining attribute 
~—— Data field length 
[| Terminating attribute 


SL Starting location (first data position) of the field 


[D] Designator 


eaa5 
t Null character (X‘00') appears as a blank space on 
the screen 


Items in the legend apply to the illustrations in the following 
discussion. 


Attributes 


Attributes are generated only when the Display Format 
Generator is used; they are not generated when the Printer 
Format Generator is used. 


The defining attribute is a nondisplay character located in 
the character position immediately preceding a data field 
and defines the characteristics of the display field that 
follows. The code for the attribute is developed by the 
format generation program based on field class and type. If 
data in an output, input, or output/input field must start 

at line 1, position 1, its defining attribute will be placed in 
the last display location (line 12, position 40 on Model 1 or 
line 24, position 80 on Model 2). Be sure this space is 
reserved when planning the rest of the display. 


Note: When data for an output, input, or output/input 
fiéld begins in line 1, position 1 of a display, that field 

is the /ast field transmitted in the 3270 text stream. The 
location of the field in the user program record area, 
however, corresponds to its location in the display. 





Defining 
attribute 


The terminating attribute is a nondisplay character located 
in the character position immediately following a data field 
of an input or output/input class. This terminating attribute 
keeps the terminal operator from keying beyond the 
defined limits (data length) of the field and provides the 
function of autoskip/nonautoskip as defined at format 
generation time (see Autoskip and Cursor Positioning). 
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“No. of sheets per pad may vary slightly. 





Output Class 





The total length of each output field on the printer/ 
display layout sheet = data field length + one for the 
defining attribute when the Display Format Generator 
is used. When the Printer Format Generator is used, 
the total length of each field on the layout sheet 
equals the data field length only. 





: The defining attribute determines the characteristics 
of the display field that follows. This attribute 
character is determined at format generation time 
based on the type as designated on the field definition 
entry. One position on the layout must be reserved 
for this nondisplayable character located immediately 
preceding the data field. 


SL The location of the first data position is entered in 
the field starting location on the field definition 
form. It must be the location immediately following 
the defining attribute character. 


~—> Data field length (does not include defining attribute) 
is entered on the field definition form. Positions on 
the layout must be reserved equal to the data length. 


Input and Output/Input Classes 


SL 








Total length on the printer/display layout sheet = field 
length + two for beginning and ending attributes (or field 
length + one if there is no allowance for a terminating attri- 
bute (see part three under Autoskip and Cursor Positioning). 





The defining attribute determines the characteristics 
of the display field that follows. This attribute 
character is determined at format generation time 
based on the type as designated on the field definition 
entry. One position on the layout must be reserved 
for this nondisplayable character located immediately 
| preceding the data field. 


SL The location of the first data position is entered in 
the field starting location on the field definition 
form. It must be the location immediately following 
the defining attribute character. 


~——-» The data field length is entered on the field definition 
form. Positions on the layout form must be reserved 
equal to the field length. The field length does not 
include either the defining or the terminating attribute. 


[4 The terminating attribute limits the amount that can 
be keyed in. Based on autoskip/nonautoskip indica- 
tion on the field definition form, this terminating 
attribute will reposition the cursor after a data char- 
acter is entered into the last position of the field. 
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SPD Class 


For SPD fields, use the following guidelines for reserving 
space on the printer/display layout sheet. 


pocpenenn 
U ee ec reel a Se | 
Locbecunse 





SPD field is the first field on a line and not the last field 
on the line, or, the previous field on the line is SPD and 
this SPD field is not the last field on the line. 


Total length allowed for this SPD field on the layout sheet 
is the field data length plus five. 


eran 
4 

rer 

f Pade 





The preceding field on the line is another class and this SPD 
field is not the last field on the line. 


Total length allowed for this SPD field on the layout sheet 
is the field data length plus eight. 





L 


The SPD field is the last field on the line and the previous 
field on the line is SPD, or, this SPD field is the only field 
on the line. 


SL 


Total length allowed for this SPD field on the layout sheet 
is the field data length plus three. 





ees 


wow doe wale a: 





O 


The preceding field on the line is another class and this 
SPD field is the fast field on the line. 


Total length allowed for the SPD field on the layout sheet 
is the field data length plus six. 





The defining attribute determines the characteristics 
of the display field that follows. This attribute 
character is determined at format generation time, 
based on the type as designated on the field definition 
entry. One position on the layout must be reserved 
for this non-displayable character. 


The designator character must immediately follow 
the defining attribute character. The designator 
character is determined at format generation time, 
based on the field definition type entry. One po- 
sition on the layout must be reserved for this 
character, 


The location of the first data position must be enter- 
ed in the field starting location on the field definition 
form. This position must be located immediately 
following the designator character. 


The field data length is entered on the field definition 
form. Positions on the layout form must be reserved 
equal to the field length. The field length does not 
include leading nulls, defining attribute, designator 
character, trailing nulls, or terminating attribute. 


Leading nulls are required when the preceding field 
on the same line is of another class. Trailing nulls 
are required unless the SPD field is the only, or last, 
field on the line. To reserve the correct number of 
positions on the layout form, refer to the guidelines 
above. 


A terminating attribute is required when the SPD 
field is the only, or last, field on the line. In either 
of these cases, one position on the layout must be 
reserved for this non-displayable character located 
immediately after the data field. The terminating 
attribute for an SPD field is used to prevent extrane- 
ous data, at the end of the current line or from the 
next line, from being transmitted along with the 
data for the SPD field during an input operation. 
Even though such a circumstance could occur only 
when using overlay screens (see index entry), all 
SPD fields ending a line are required to have the 
terminating attribute. 


When SPD is first or last field on a line: 










aoa 


THIS IS AN SPD FIELD 










If SPD field is first on 
a line, leading nulls (X’00’) 
are omitted. 





If SPD field is last on 
a line, trailing nutls 
(X’00’) are omitted but 
a terminating attribute 
is needed. 










When SPD is not first or last field on a line: 


Defining attribute 
(nondisplay) 





3 null (X‘00'} 
characters precede 












defining attribute 3 nulls 
if preceding field (X‘00’) 
on same line is not Defining attribute } immediately 






follow data. 





an SPD field. (nondisplay) 


The entire field with its attributes and designator must be 
on the same line. 


Note: For a type 5 SPD field, the designator and data are 
also not displayed. 
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AUTOSKIP AND CURSOR POSITIONING 


The way autoskip functions with input and output/input 
fields depends upon the relative positioning of successive 
fields. 


1. When there are one or more spaces between the trail- 
ing attribute of one field and the defining attribute 
of the next field: 





Without autoskip, the cursor is positioned after With autoskip, the cursor is 

the trailing attribute. TAB or SKIP must then positioned at the first data 

be pressed to move the cursor to the first char- character of the next unprotected 
acter position of the next unprotected field. field. 


2. When the trailing and defining attributes are in 
adjacent positions: 


unprotected CO 





L Cursor positions at the first character of the unprotected 
field with or without autoskip. 


unprotected 


protected ) 





Without autoskip, the cursor positions at the first character With autoskip or if protected field is a type 6 input or 
of the protected field (unless this field is a type 6 input output/input, the cursor positions at the first character 
or output/input field). Use TAB or SKIP to move cursor of the next unprotected field. 


to next unprotected field. 
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3. When two spaces were not allowed between fields: 


following 





field 
If two spaces were not allowed by the application programmer during layout 
of the fields, the terminating attribute is dropped. The single space between 


the fields will be used for the attribute character of the next field. 





next field 
(protected) 


The cursor positions at the first data character of the next 
field (unless this field is a type 6 input or output/input 
field). Use TAB or SKIP to move the cursor to the next 
unprotected field. 


Defining Data 
Defining Data at Format Generation Time 


During generation time, the user may provide data on the 
field definitions for output, output/input, and SPD fields. 
Such data is in the form of characters and/or spaces up to 
the specified field length. 


The length of each field is defined at format generation 
time (see Figures 8-3 and 8-4). Each SPD field must be 
contained on one line. Therefore, the field length of SPD 
fields cannot exceed 37 for a Model 1 screen or 77 for a 
Model 2 screen. All other fields cannot exceed 240 charac- 
ters. Minimum length for all fields is one. 


See Data in Numeric Fields for techniques in handling 
numeric data. 


Defining Data at Execution Time 


Data can be provided for all but input fields during 
execution time. The length of data to be provided must 
equal the field length specified at format generation time. 
Less data than the amount specified by the field length 
cannot be provided. 


See Data in Numeric Fields for techniques in handling 
numeric data. 





unprotected CO 
fl rrr 


If the next field is a type 6 input or output/input field, the 
cursor positions at the first data character of the next un- 
protected field. 


Data Entry at the Terminal 


The terminal operator, when keying data for input fields, 
must start with the first character location of the field. 
Starting with any other position causes the control routine 
to return all blanks in the field. 


See Data in Numeric Fields for techniques in handling 
numeric data. 


Data Passed to the Application Program 


On input from the 3270 terminal, alphameric data is padded 
on the right with spaces to the field length when less data 
than that required by the field Jength is entered by the ter- 
minal operator. 


Numeric data, received from numeric fields, is right-adjusted 
and padded with blanks on the left to the field length when 
less data than that required by the field length is entered by 
the terminal operator. 


For input and output/input fields, it is assumed that data 
will always be received from the terminal. If no data is 
received, the fields are returned with blanks. 


When the terminal operator uses the ENTER or PF keys to 
initiate the input operation and data is not received from 
the terminal for SPD selection, the field (alphameric) will 
be filled with spaces. Since the designator is not passed as 
data, the field length should not include the designator 
character, 
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Figure 8-3. Display Format Specifications Sheet 
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When the SPD attention field is used to generate the !|/O 
pending condition, field data is not included with input 
from SPD selection and SPD attention fields from the 
terminal. The fields passed to the application program are 
filled with spaces except for a greater than (>) character in 
the leftmost position for any field in which the modified 
data tag was ON. By testing a field, the application pro- 
grammer can determine those fields in which the modified 
data tag was or was not set. 


Fields in the users input record area must be the same 
lengths as the field lengths specified on the field definition 
forms. Field lengths are used by the Display Format Con- 
pon peneine in moving data into the user’s input record 
areaf 


Data in Numeric Fields 


All data in numeric fields should be right-justified when 
entered at generation time. Negative values in numeric 
output/input fields are provided at generation time by en- 
tering the minus sign (-) after the rightmost numeric digit. 
For example, a negative‘thirty-five would be given as 35-. 
Space for the negative sign must be allocated in the gen- 
erated format when defining the field length. If numeric 
data is to be later entered by the terminal operator, the 
numeric fields may be set to zeros so that the field is visi- 
ble to the operator. 


Note: Continuation cards must be provided if the nu- 
meric field is designated as being longer than forty digits 
(or thirty-nine digits and a minus sign). 


Data provided (with Put Message or Put Override opera- 
tions) in numeric fields at execution time must be the same 
length as the field length specified at generation time. Nu- 
meric fields are always right justified. Negative values pro- 
vided for numeric input and output/input fields must com- 
bine the minus sign (-) with the rightmost digit. For 
example, a negative thirty-five is given as 3N. Before send- 
ing the message to the 3270, DFCR will move the numeric 
digits one position to the left, convert the N to a five and 
place a negative sign in the rightmost position of the field. 
Space for the negative sign must have been allocated at 
generation time. DFCR also moves the digits of a positive 
number one digit to the left. 


Note: In aone-position numeric output field, the minus 
sign would be all that would be sent for a negative value. 


To enter data in numeric fields, the terminal operator should 
either 


®@ Right-justify data in the field and left pad with zeros or 
blanks, or 


@ First key in the numeric data Jeft-justified; press ERASE 
EOF; and then press either SKIP or TAB. The cursor 
will be positioned at the next designated cursor location. 
On input, DFCR will right-justify the data in the field 
and pad with leading blanks if less data than the field 
length is received. DO NOT press the space bar after 
pressing ERASE EOF. 


Numeric fields are not examined by DFF for valid numeric 
characters. The application program is responsible for 
validation of its input data. 


The terminal operator must enter negative numerics in a 
numeric field by entering a trailing negative sign in the 
field. For example, a 35— is entered. DFCR will right- 
adjust the numerics and pad with blanks on the left to 
the field length when less data than that required is 
entered. The five will be converted to an N and the appli- 
cation program receives a right-adjusted 3N as data input 
for the field. 


Note: \f the minus sign (—) was the only character 
received, an X‘DO’ (equivalent to a —O) is returned to 
the application program. 


Since some languages are more restrictive than others, 
particularly in the form of numeric data supported, the 
application programmer must be aware of their differences 
and inform the terminal operator what characters can be 
used. If the data conventions of the language are not 
enforced by the compiler generated object code, the appli- 
cation programmer must validate the data keyed by the 
terminal operator. 


Number of Fields 


A total of 256 fields can be defined for a printer or display 
format. This does not include F-type output fields. Any 
number of these fields may be defined. The combined total 
of Input, Output/Input, and SPD fields cannot exceed 200 
fields. 
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A maximum of seven SPD fields in the 3277 or 3275 
Model 1 or thirteen SPD fields in the 3277 or 3275 
Model 2 may be on any given display line. This is, of 
course, because the minimum length of an SPD field is 
six with no trailing attribute or four if there is a trailing 
attribute. The minimum of six consists of: the defining 
attribute, the designator, one data character, and three 
trailing nulls. The last SPD field on a line can require as 


few as four positions since the trailing nulls are not required. 


When mixing detectable and nondetectable fields, a maxi- 
mum of 15 defining and/or terminating attributes may be 
on a given line. Whereas all fields generate a defining 
attribute, input and output/input fields generate a defining 
and terminating attribute. 


Note: \t is possible to define up to 15 fields on a line by 
positioning fields following the input and output/input 
fields so that their defining attribute overlays the 
terminating attribute of the previous field. However an 
SPD field following an input and output/input field will not 
overlay the previous terminating attribute. The leading 
nulls cannot overlay terminating attributes. See Chapter 8 
for the use of nulls with SPD fields. 


RECORD CONCEPTS 


Fields are received from and passed to the application 
program as data records. The user defines data record 
formats by defining the fields on the field definition 
forms. 


Display Output Record Format 


When writing the initial display format, data can be supplied 
during execution time for output, output/input, and SPD 
fields. If data is to be supplied, the format of the associated 
output record is determined by the order and field lengths 
of the fields as they are defined on the field definition 
form. Field names, field lengths, field end positions (for 
RPG SUBR92 use), and length of output record area 
required are listed on the printed output from DFGR. 


Printer Output Record Format 


When the initial printer format is written, data can be 
supplied during execution time. If data is to be supplied, 
the format of the associated output record is determined 
by the order and field lengths of the fields as they are 
defined on the field definition form. Field names, field 
lengths, field end positions (for RPG SUBRQ2 use), and 
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length of output record area required are listed on the 
printed output from PFGR. 


Input Record Format 


Since it is possible to receive data from each input, output/ 
input and SPD field defined, the input record area must 
provide an assigned location for every field. The format of 
the associated input record area is determined by the order 
and field lengths of the fields as they are defined on the 
field definition form. The symbolic name, field length, 
assigned end position for each input field (for RPG 
SUBRQ2 use), and length of input record area required are 
listed on the printout from DFGR. 


Note: With the Put Overrides operation, the application 
programmer can choose between receiving input from all 
fields or only from selected fields (see Put Override). 


The order of processing an input record area is: 
1. Examine the CCP return code. 

2. Examine the attention identifier (AID). 
3. Process the fields in the input record area. 


The attention identifier (AID) is a single character immed- 
iately preceding the input fields in the user’s input record 
area. The AID is set by the terminal when the operator 
takes any action that produces an I/O interruption. The 
AID identifies the action (such as using the selector pen 
onan SPD attention field) or key (program function or 
program access keys) that caused the condition to be 
generated. For a complete discussion on AID, refer to 
!BM 3270 Information Display System Component 
Description, GA27-2749, The return code and the AID 
must be examined before processing of fields in the input 
record area. The effective input length includes the AID 
character. 


Note: AID characters are shown at the bottom of the 
printer/display layout sheet (Figure 8-2). The AID for 
TEST REQUEST (0) is received by the application program 
only when the block length specified in the terminal attri- 
butes set is not large enough for the test being run (see 
BLKL parameter of TERMATTR assignment statement in 
CCP System Reference Manual). 


For CCP return code considerations, see Appendix E. 


DISPLAY FORMAT GENERATOR 


The display format generator routine does not run under 
the contro! of CCP. DFGR generates a 3270 display format 
from display format specifications. DFGR performs the 
following functions: 


1. Reads display format specification statements. 


2. Produces a printout of the specification statements, 
analyzes the specifications for errors, and logs 
diagnostic error messages as required. 


3. Builds the display format as a two-part table structure: 


a. Field Descriptor Table (FDT) — a table of 
descriptive field information including the symbolic 
name of the field. 

b. 3270 Data Stream — containing output data if 
provided, and 3270 device-dependent control 
information required for formatting all fields 
defined. 


4. Provides a printout of field names, in the order in 
which they must appear in the output record area 
if data from the Field Descriptor Table is required 
by the application program using the Display 
Format Facility. 


5. Produces a printout of all fields defined for input 
and the order in which they will appear in the input 
record area. 


6. Calculates and prints the following: 


a. Length of the output record area required in DFF 
program 

b. Length of the input record area required in 
DFF program 

c. Decimal length of the field descriptor table 

d. Decimal length of the 3270 output data stream 

e. Decimal length of the 3270 input data stream 


7. Places the display format in a work file (SWORK) on 
disk and then catalogs the display format in an object 
library on disk. 


Note: \f printer control on DFGR is used for a Katakana 
printer, unpredictable results can occur because of new 
line and end-of-message considerations. For this reason, 
PFGR should be used to build a printer format for a 
Katakana printer. 


Printer/Display Layout Sheet 


The printer/display layout sheet (Figure 8-2) is a planning 
device. The application programmer uses it to plan the for- 
mat and layout of the fields on the display. The completed 
layout is then used as a guide when filling out the display 
control and field definition forms (see Figures 8-6 and 8-7). 


Notice the heavy line after position 40 and line 12 which 
marks the boundary of the 480-character display. The 
heavy line after position 80 and line 24 marks the boundary 
of the 1920-character display. The entire page is used for 
the layout of printer formats. 


Display Control Form 


The display control form provides special information about 
the display format which, in general, is unrelated to the 
fields being defined. One display control form is required 
and must precede all field definition forms. (Both forms 
appear on the Display Format Specifications sheet—see 
Figures 8-5 and 8-7. Additionally, both forms appear on 

the reverse of the sheet to be used as a template to verify 
the position of data in the DFGR listings.) 
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Figure 8-5. Display Control Form is the First of Two Forms on the Display Format Specifications Sheet 


See Figure 8-5 for the location of the following items: 
1 | Form Type—Column 1 


The preprinted character C identifies this as the 
display control form. 


Display Name—Columns 2-7 


This entry is used to assign a unique name to a display 
format. Entries in columns 2 and 3 are $Z. The 
remaining characters in the name may contain any 
combination of alphabetic and/or numeric characters 
plus any of the characters $, #, or @. Blanks may not 
appear between characters in the name. All applica- 
tion programs using a particular display format must 
refer to it by its assigned symbolic name because each 
display format is catalogued in the object library 
under its symbolic name. The application program 
uses the format’s symbolic name when issuing a 

PUT Message. 


Field Name for Initial Cursor Position—Columns 8-13 


Enter the name of the field where the cursor is to be 
positioned. Ifa field name is specified, the cursor 
will be positioned at the first character location of 
the data field. The field must be unprotected. The 
field name must begin with an alphabetic character 
or one of the characters $, #, or @. The remaining 
characters can be any combination or alphabetic, 
numeric characters or any of the characters $, #, 

or @, No imbedded blanks are allowed. 


If the field name is not specified, the clear before 


writing entry (column 15) determines the initial 
cursor position. 
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Display Size—Column 14 


Enter a 1 in this column if the display format is to be 
used with a 480-character display or printer. 


Enter a 2 in this column if the display format is to be 
used with a 1920-character display or printer. 


If more fields are defined than can be displayed, an 
error message occurs and all remaining field defini- 
tion forms will be read but not processed. 


Clear Before Writing—Column 15 


Enter Y if the screen is to be cleared before writing 
this display format. An entry of Y will also cause 
the cursor to be positioned at line 1, position 1, of 
the display. The cursor can be repositioned by 
specifying a field name in columns 8-13. 


Enter N if the screen is not to be cleared before writ- 
ing this display format. In this case, the cursor will 
not be positioned unless columns 8-13 contain a 
field name; it remains at whatever position it 
happened to be on the screen before the display 
format was written to the screen. 


If this column is blank, the default entry Y is assumed. 


The entry N must be used if the format is to be an 
overlay format (see index entry). 






G WCC — Columns 16-18 


nenmae. 
Operation 
Format 

















Enter the write control character in column 16 or es zs 
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17 or 18. Use Figure 8-6 to select an entry for E & ~ = & els S45 

column 16. The WCC allows the user full control z ¥ 2 2 538 8 2 8 @ 8 2 

over certain device operations such as starting the s 2 |& 5 eS(s S|ss\e5 
. ‘ < ° £ au 5 Pe] 5 - 5 ” 

printer and resetting the keyboard. 3 % |E 9 aig fla Ela = 

la lszZ BzE\SclsElQEz 





If there is an entry (X) in either column 17 or 18, a 
default write control character is assigned and any 
entry in column 16 will be ignored. 
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default are as follows: Yes 
Default WCC 
Column (column 16) Operations Performed Yes 


17 (Screen) Character-C Restore the keyboard. 
Reset the modified data 
tags. 


WaWWalide 





‘This character Is converted internally to hex 6A for a WCC by 


18 (Printer) Character-Q Start the print operation. DFGR when generating a format, and by DFCR when using 


if Display Set length of character the WCC in a Put Override operation. 
Size entry line to 40. 
is 1 Figure 8-6. Write Control Characters 


if Display Character- 8 Start the print.operation. EEA (Reserved)—Columns 21-23 are reserved and must be 
Size entry Set length of character left blank. 


is 2 line to 80. 


Disk Storage Unit for Display Formats—Columns 19- 
20 


Enter R1, F1, R2, or F2 to specify the location of the 
object library where the display format is to be stored. 
If columns 19 and 20 are blank, the display format 
will be placed on the disk from which the display 
format generation routine was loaded. 


When executing with CCP, all display formats must 


be stored either on the CCP program pack or on the 
DSM system pack. 
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Printer Control—Columns 24-71 


New line and end-of-message orders can be included 

in the display format for control of printouts. Each 
order occupies a data position in the display and is 
executed only when printing. The orders appear as the 
graphics ‘5’ and ‘9’ respectively on a display screen 

or during a printout when using a specified line 

length format in the WCC, New line and end-of- 
message orders are ignored and treated as spaces if 

the field in front of either of these orders is a non- 
display/nonprint field. 


if WCC is specified in column 16, which will define 

a format for a printer in an unformatted mode (not 
40 or 80 characters per line), then new line (NL) 

and end-of-message (EM) orders should be specified. 
This may be accomplished in one of two ways {or 
both): specify up to 23 NL orders and one EM in 

the control card, and/or specify any number of NL 
orders and one EM order in the field definition state- 
ment by use of the reserved keywords @@@NL and 
@@@EM. It is suggested that all NL and EM orders 
be specified using only one or the other form (con- 
trol card or field definition statement using the key- 
words}. If both forms are used and an NL is specified 
on the field definition statement (@@@NL) for 

a position in a format after the last new line speci- 
fied on the control card (which is assumed to be an 
EM), that last control card entry will still be con- 
sidered an EM order. Since the reserved keyworcls 
allow NL and EM orders to be specified in the same 
order and method as fields, it is suggested that the 
keyword method of specifying NL and EM orders 

be used for unformatted printer operations (See 
Additional Functions for the Field Definition State- 
ment Chapter 8). For the 3288 printer equipped with 
the vertical forms control feature, a reserved keyword 
(@@@FF) will insert the forms feed order into the 
text stream. There is no way of specifying this order 
on the contro! card. 


To specify control card NL and EM orders, each en- 
try consists of a line (two columns) and a position 
(two columns). If the column 14 entry is 1 (for small 
screen), enter a number from 01 to 12 under line and 

a number from 01 to 40 under position. If the column 
14 entry is 2 (for large screen), enter a number from 
01 to 24 under line and a number from 01 to 80 

under position. 


Each entry, with the exception of the last entry, will 
cause an NL order character to be inserted into the 
specified location. The last entry will cause an EM 
order character to be inserted. If only one entry is 
specified, the EM order character will be inserted. 


The new line and end-of-message orders specified on 
the display control form will not be diagnosed. An 
NL or EM may overlay another field, or an attribute 
with no error messages or halts given. 


{f NL or EM orders specified on the control card are 
used with the line/partial-line duplication function 
(@@@DP), a warning message and a halt (U-F1) is 
issued at the end of generation. See the Display For- 
mat Generator messages. 


Notes: 

1. For a discussion of new line and end-of-message orders, 
refer to /BM 3270 Information Display Component 
Description, GA27-2749. 

2. If printer control on DFGR is used for a Katakana printer, 
unpredictable results can occur because of new line and 
end-of-message considerations. For this reason, PFGR 
should be used to build a printer format for a Katakana 
printer. 


10) Continuation—Column 72 


If more than twelve printer control entries are 
required, place an X in column 72 and make remain- 
ing entries in columns 24-71 of the second card. 
(Columns 2-23 of the second card must be blank.) 
One continuation card is allowed. This provides for 
NL control for up to 23 lines with EM control for 
the last line. 


11] Identification-Sequence—Columns 73-80 
Enter any character for sequential identification. 


These columns will be ignored other than to print 
them as part of the statement. 


This page intentionally left blank 
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Field Definition Form 


An understanding of how to define fields (see Field Con- 
cepts) is necessary to correctly complete the field defini- 
tion form. Refer to the printer/display layout sheet and 
the display control form while completing the field defini- 
tion form. Each field in the display format must be speci- 
fied on a field definition form. Enter an * in column 1 to 
identify a comment statement. Comments can be used to 
include notes on the listing produced by the Display 
Format Generator program. Placement of the statements 
is not restricted (may appear before the display control 
form, between continuation cards, etc) during a single-format 
build. Placement of comments is not restricted when using 
multiple-format builds, but all comments before the 
display control form of the next format build are printed 
with the previous format build. See Figure 8-7 for location 
of items described below: 
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Form Identifier—Column 1 


The preprinted character ‘F’ identifies this as a field 
definition form. 


Field Name—Columns 2-7 


Enter in columns 2-7 a unique field name (up to six 
characters in length). The first character must be 
alphabetic or one of the characters, $, #, or @. Re- 
maining characters can be any combination of alpha- 
betic or numeric characters or the characters, $, #, or 
@, Imbedded blanks are not allowed. 


The field names as defined are the symbolic names 
used with Put Overrides applications. 


Note: For more considerations, see Additional 
Functions for the Field Definition Statement in 
this chapter. 


Field Starting Location—Columns 8-11 


A line (two columns) and a position (two columns) 
entry define the leftmost character position of the 
field. Allowable entries are limited by the display 
size (see column 14 of the display control form). 

\f the display size entry is 1 (for small screen), enter 
a number from 01 to 12 under line and a number 
from 01 to 40 under position. If the display size 
entry is 2 (for large screen), enter a number from 01 
to 24 under, line and a number from 01 to 80 under 
position. Field starting locations must be specified 
in numerically increasing order (see Planning the 
Printer/Display Layout). 


Field Length—Columns 12-14 


The minimum field length is one. The maximum 
length for an output, input, or an output/input field 
is 240 positions. An SPD field must be contained on 
one line and is therefore limited to a length of 37 or 
77 depending upon the display size (see Planning the 
Printer/Display Layout). 


Note: For more considerations, see Additional 
Functions for the Field Definition Statement in 
this chapter. 


Output, Type—Column 15 


Enter 1, 2, or 5 (see Field Concepts, earlier in this 
chapter). 


Output, Data Source—Column 16 


Enter E if data is provided when writing the initial 
display format during execution by the application 
program, 


Enter a G if data is generation-defined (data is 
entered in columns 32-71) and a Put Override is 

used to override the field during execution. To save 
main storage, enter an F for an output field having 
generation-defined data (in columns 32-71 ). Enter- 
ing an F eliminates the Field Descriptor Table (FDT) 
entry, which saves 14 characters of storage. However, 
the lack of this FDT entry eliminates the capability 
of overriding the field during execution. 


Either a G or an E can be entered and a Put Override 
can still be used to override the field at execution time. 


If this entry is blank, the default G is assumed. 


Input, Type—Column 17 


Enter 1, 2, 3, 4, 5, 6, or 7 (see Field Concepts, earlier 
in this chapter). 


Input, Automatic Skip—Column 18 
This entry determines the terminating attribute. 
Enter Y in column 18 if automatic skip function 


is to be performed (see Autoskip and Cursor 
Positioning). 


Enter N if automatic skip function is not to be per- 
formed. 


Default is N if entry is left blank. 
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Figure 8-7. Field Definition Form on the Display Format Specifications Sheet 


oO Output/Input, Type—Column 19 Enter N if automatic skip function is not to be per- 
formed. Default of N is assumed if entry is left 
Enter 1,2,3,4,5,6,7, or 8 (see Field Concepts, blank. 


earlier in this chapter). 
SPD, Type—Column 22 
Ee) Output/input, Data Source—Column 20 
Enter 1, 2, 3, 4,5, 6, or 7. See Field Concepts, earlier 


Enter E if data is provided when writing the initial in this chapter. 

display fromat during execution by the application 

program, SPD, Data Source—Column 23 

Enriter a G if data is generation-defined and data is Enter E if data is provided when writing the initial 
entered in columns 32-71. Either a G or an E may display format during execution by the application 
be entered and a Put Override can still be used to program, 


override the field at execution time. 
Enter a G if data is generation-defined and data is 


If this entry is blank, the default G is assumed. entered in columns 32-71. Either a G or an E may 
be entered and a PUT Override can still be used to 
BE Output/input, Automatic Skip—Column 21 override the field at execution time. 
This entry determines the terminating attribute of TE] (Reserved)—Columns 24-31 must be left blank. 


the field. Enter Y if the automatic skip function is 
to be performed (see Autoskip and Cursor 
Positioning). 
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Data--Columns 32-71 


Data may be provided for Output, Output/Input, or 
SPD fields. Data must not exceed field length as 
specified in columns 12-14. 


If data exceeds 40 characters in length, place an X in 
column 72 and continue entering data-in column 32 
of the next line (leave columns 2-31 blank). 


(3 Continuation—Column 72 


If the data entry must continue beyond column 71, 
place an X in column 72 and continue entering data 
in column 32 of the next line. A maximum of five 
continuation lines are allowed. 


Identification-Sequence—Columns 73-80 


Since these columns are ignored other than to print 
them as part of the statement, they may contain any 
characters, 


Additional Functions for the Field Definition Statement 


Printer Control 


An optional method of providing new line and end-of- 
message printer contro! is to request the generation of 
these orders on Field Definition statements. An additional 
control called forms feed can be specified for those printers 
having the Vertical Forms Control feature. The new line, 
end-of-message, and forms feed orders on field definition 
statements are checked for position. If there are control 
characters overlapping other fields or attributes, an error 
message and halt are issued. The position of the new line 
and end-of-message orders on the display contro! form are 
not checked. 


If printer control on DFGR is used for a Katakana printer, 
unpredictable results can occur because of new line and 
end-of-message considerations. For this reason PFGR 
should be used to build a printer format for a Katakana 
printer. 


8-28 


To specify printer control on a Field Definition statement: 


Form Type—Column 1 
Contains the preprinted character F. 


Name —Columns 2-7 
@@@NL — Signifies a new line order is to be 
generated in the display format 
(see note). 


@@@EM — Signifies an end-of-message order is to 
be generated in the display format. 


@@@FF — Signifies a forms-feed order is to be 
generated in the display format. This 
order is valid only for printers having 
the Vertical Forms Control feature. 
When valid, the forms-feed order is 
printed as a blank; when invalid, it is 
displayed as a graphic < (see note). 
See /BM 3270 Information Display 
System Component Description, 
GA27-2749. 


Note: There is no restriction on the number of new 
line (@@@NL) or forms-feed (@@@FF) orders that 
can be generated. 


Field Starting Location—Columns 8-11 
Enter the line number in columns 8 and 9, the 
position number in columns 10 and 11. These 
numbers indicate where the order will be in the 
format. Each order occupies one position in a 
format. These orders should be provided in 
numerically increasing order. 


DFGR Line/Partial-Line Duplication 


Line/partial-line duplication allows generation of duplicate 
fields on consecutive lines without requiring Field Definition 
statements for each duplicate field. Instead, one Field 
Definition statement is required to place the duplicate 

fields on the desired tine. To allow duplication, enter the 
fotlowing on the Field Definition form: 


Form Type—Column 1 
Contains the preprinted character F. 


Field Name—Columns 2-7 
@@@DP identifies this as a duplication statement. 
This means that this is a request to duplicate a 
field(s) defined in the Field Definition statement(s) 
for the previous line. 


Field Starting Location—Columns 8-11 
The line number, columns 8 and 9, identifies on 
which line to generate the duplicated fields. The 
fields will be duplicates of the fields for the last 
defined line. Any number of blank lines can 
be left between the original line and the line on 
which the duplicate fields are being generated. 
The position number, columns 10 and 11, is an 
optional entry. It gives the position number on 
the line where duplication is to begin. If no 
entry is made, the default is position 1. !f the 
position specified is in the middle of a field, DFGR 
starts to duplicate at the start of the next field. 


Field Length—Columns 12-14 


Number of Fields: The number entered specifies 
the number of fields to duplicate (see columns 8-11 
for start position). If the number of fields is not 
specified or if the number of fields specified is 
greater than the number of fields available to be 
duplicated, all fields after the start position of 

that line (columns 8-11) are duplicated. 


Number of Lines: \f an @ is entered in column 12, 
followed by a number in 13 and 14, this number 
specifies the number of times to duplicate the 

last line with field definitions. If columns 13 and 
14 are left blank it will duplicate the line once. 


No other entries on the duplication statement 
are recognized. 


DFGR Considerations for the Duplication Function 


@ Ifa line being duplicated contains both fields defined 
by Field Definition statements and fields generated by 
a previous duplication statement, only the fields defined 
by Field Definition statements are duplicated. 


@ Field names are assigned to fields generated under the 
duplication process. The names have the format 
‘DPllpp’. The ‘DP’ indicates it is a duplicate field and 
‘Ilpp’ are the line and position where it is located. You 
should avoid defining other fields using this convention 
because you could get duplicate field names. 


®@ fa field being duplicated extends to another line, or 
lines, the entire field is copied. 


© If any DFGR warning messages were issued (but no 
termination messages), a halt (U-F1) is issued. The 
options available are: 


0 — Catalog the format and ignore the warnings. 


3 — Cancel the program and DFGR will go to end 
of job. 


Examples of Duplication Functions: The following 
examples are some of the ways to use the line and field 
duplication functions. The duplication function is indicated 
by ‘@@@DP’ in columns 2-6. The fields that are generated 
from this duplication function are between the lines of 
asterisks, starting with the line with the comment 
‘GENERATED DUPLICATION FIELDS’ and ending with 
the line with the comment ‘END OF GENERATED 
DUPLICATION FIELDS’. 
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C$ZTSTL 2Y XRL 


FA 22 31E 
FB 3 5 402G DUPLICATED ON LINE 4 
Fa@aaNlL. 350 DUPLICATED ON LINE 4 


a 

FaaapP 4 

Joblopolodolioiicobiciosiiopiolisiisielieoblosopisotoiistoolsteoistoe GENERATED DUPLICATION FIELDS 

FDP040504 5 402G DUPLICATED ON LINE 4 

Faa@aNL 0450 DUPLICATED ON LINE 4 

Jeloieiolojeloiaiaioloolokioloicloictociojcioloojeeioteslolsisjolsoioeloapiciooietaissiok END OF GENERATED DUPLICATION FIELDS 
at En ee ee 










FC 79 24G er 
Fa@aFF 716 Eg 
FD 718 205E 4k DUPLICATED ON LINES 9,10,11 
FE 744 826 x 
Fa@d@aNL 750 3 tek 


FaaaDP 9 a 3 

Jlokeloogclonicigoloioioianiojioioooioimociooioieicicoiojaocoioisalokeieioiok GENERATED DUPLICATION EIELDS 
FDP090909 9 21G ao 

FaaaFF 0916 3 

FDPO9L80918 205E 3k DUPLICATED ON LINES 9510,14 

FDP094'L0941, 826 * 

Faa@aNL 0950 3 eae 

FDP100910 9 216 sek 

FaaaFF 1016 x 

FDP10131018 205E ek DUPLICATED ON LINES 9510,11 

FDPLO4:L1041 826 * 

Faa@aNL 1050 3 sek 

FDP110911 9 21G nek 

FoaaaFF 1116 He 

FDP111381418 205E eke 

FDPLI4LL141 826 x 

FaaaNL 1250 3 ok 
lleiclojolaloicjokioioictoloitekioiaiciooienioopijopioogooocksemgeopooiooe END OF GENERATED DUPLICATION FIELDS 





FagaFF 123 9 

FTESTA 14 2 3 7GY 

FTESTB 146 8 8GY 

FTESTC 1420 30 7GN DUPLICATED ON LINE 15 
FTESTD 1454 226 DUPLICATED ON LINE 15 
















FaaaDP 15200 1 
Jololololololotolojolojoloteiofolsiolotoloioiojaloloiooiciolejolotelolololoielatotelaelojajatottola 
FDP15201520 30 7GN DUPLICATED ON LINE 15 
FDP15541554 226 DUPLICATED ON LINE 15 
Jeloinlolooiololololooiciolotojoiolololciotololojoljolojolelojajoloiooloiaioojosioloioiiotsioio END OF GENERATED DUPLICATION FIELDS 


GENERATED DUPLICATION FIELDS 









FTESTL 20 2 3 7GY 
FTEST2 206 8 8GY 


FTEST3 2020 30 TGN DUPLICATED ON LINE 22 
FTEST4 2054 226 DUPLICATED ON LINE 22 







GaaaDP 2220 3 
Jolointololoiaioiciololoicioleiololoiafolaioiojooiojajoloioloioioloioiaiolejolsioioiolotoisilolsiook GENERATED DUPLICATION FIELDS 
FDP22202220 30 TGN DUPLICATED ON LINE 22 

FDP22542254 226 DUPLICATED ON LINE 22 
Jobloloiooinioiololoisioleiaioloiojotejojooioolotajalojajoleiaioloioioiioloiololsioiolotaioisioke END OF GENERATED DUPLICATION FIELDS 









FTSTL 23 41 20 7GY DUPLICATED ON LINE 24 
FTST2 2325 1516 DUPLICATED ON LINE 24 
FTST3 2345 ‘LF 

FTIST4 2349 5 8GN 
















FaaaDP 241 2 
Jebloliojoinioicjoloioisiolojoiepelojoictoio}etajojojoisfoiojolotojoloiololololotoloioiatotolootelok GENERATED DUPLICATION FIELDS 
FDP240124 1 20 TGY DUPLICATED ON LINE 24 

FDP24252425 151G DUPLICATED ON LINE 24 

Jolololpeloieisiolsiciolok Joloioiotojojojojojoioioioiajolaioiolsiaiotojoloioololofoleisiolsicioiok END OF GENERATED DUPLICATION FIELDS 








FaaaEM 2525 
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Whole Line Duplication (Columns 12-14 blank) 


The duplication instruction (@@@DP) indicates 
duplication of fields on line 4. Columns 12-14 on 
the duplication card are blank, so the default is to 
duplicate one whole line. This would be the same as 
specifying @01 in columns 12-14. One field and one 
new line are defined on line 3, which is the line 
previous to line 4, This field and new line are 
duplicated on line 4. , 


Whole Line Duplication (Columns 12-14 non-blank}) 


The duplication instruction (@@@DP) indicates dupli- 
cation on lines 9, 10 and 11. Column 12 contains 
the character ‘@’ which indicates line duplication. 
The character 3 in column 14 indicates the previously 
defined line is to be duplicated three times. Since 
nothing is specified in the position columns (columns 
10 and 11), the whole line will be duplicated. There 
are three fields, a forms-feed order (@@@FF) and a 
new line order (@@@NL) on line 7. Since line 8 
contains no fields or forms-feed orders, the entries 

on line 7 will be duplicated on lines 9, 10 and 11. 


Partial Line Duplication 


The duplication instruction (@@@DP) indicates 
duplication on line 15 of everything on the previous 
nonblank line from position 20 to the end of that 

line. Column 12 contains the character @ which indi- 
cates line duplication. The character 1 in column 14 
indicates the line is to be duplicated one time. The 
characters 20 in columns 10 and 11 indicate everything 
from position 20 to the end of the line should be 
duplicated. In this case two fields, TESTC and 
TESTD, will be duplicated on line 15. 


Field Duplication 


The duplication instruction (@@@DP) indicates 
duplication on line 22 of three fields from the 
previous nonblank line, beginning at position 20. 
Column 12 is blank, and column 14 contains a 
character 3 indicating field duplication. Three fields 
were specified to be duplicated but only two fields 
were specified on line 20 from position 20 to the 
end of the line. In this case only these two fields 
are duplicated. 


Field Duplication 


The duplication instruction (@@@DP) indicates 
duplication on line 24 of the two fields from the 
previous nonblank line beginning at position 1. 
Column 12 is blank indicating field duplication, 
and column 14 contains a character 2, indicating 
two fields are to be duplicated. In this case the 
first two fields from line 23 are duplicated on 
line 24, 
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OCL Considerations for the Display Format Generator 


The following OCL statements are required when either 
single or multiple formats are built: 


// LOAD $CCPDF unit 


R1 
F1 
R2 
F2 


// FILE NAME-$WORK,UNIT- PACK-packid, 


RETAIN-S,TRACKS-2 
// RUN 


When reading from the system input device, be sure that 
the display format statements immediately follow the 
RUN statement. A /* follows the format statements. The 
statements are read from the system input device and 
written into a $SOURCE file. If the display format state- 
ments require more than five tracks of a file, define a 
$SOURCE file with an adequate number of tracks. If a 
$SOURCE file OCL statement is not specified, a 5-track 
$SOURCE file is automatically allocated on the unit from 
which $CCPDF was loaded. 


When reading from the source library, specify a $SOURCE 
file with enough tracks to contain all the display format 
statements in the source library. A COMPILE is also 
required with the following parameters: 


Ri 
F1 
R2 
F2 


// COMPILE SOURCE-name of source data, UNIT- 


where UNIT is the location of the source library 


Notes: 

1. For multiple format builds in a single run, the input 
stream must not contain delimiters between the display 
formats. Instead, the C in column 1 of the display con- 
trol form indicates the start of another input. 

2. Enter an asterisk (*) in column 1 to identify a comment 
statement. Comments may be used to include notes on 
the listing produced by the Display Format Generator 
routine. Comments can be placed anywhere in the for- 
mat build; however, on multiple format builds, all com- 
ments entered before the display control form of the 
second or later format builds are printed with the previous 
format build. 
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Display Format Generator Diagnostic Messages 


During its processing, the display format generator (DFGR) 
diagnoses errors in the Display Format Specifications and 
logs diagnostic messages on the system logging device. Refer 
to the CCP Messages Manual, GC21-5170, for a list of the 
diagnostic messages. 


Since DFGR calls the Overlay Linkage Editor to put the 
formats into the object library, it is possible to get Overlay 
Linkage Editor halts when using the DFGR. 


PRINTER FORMAT GENERATOR ROUTINE (PFGR) 


The Printer Format Generator routine does not run under 
the control of CCP. PFGR generates a 3270 printer format 
from printer specifications in the following functional steps: 


1. Reads printer format specifications statements. 


2. Produces a printout of the specification statements, 
analyzes the specifications for errors, and logs diag- 
nostic error messages as required. 


3. Builds the printer format as a two-part table structure: 

a. Field Descriptor Table (FDT) — containing descrip- 
tive field information, including the symbolic 
name of the field 

b. 3270 Data Stream — containing output data, if 
provided, and 3270 device-dependent control 
information required for formatting all fields 
defined 


4. Provides a printout of field names, in the order in 
which they must appear in the output record area if 
data from the Field Descriptor Table is required by 
the application program using the Display Format 
Facility. 


5. Calculates and prints: 
a. Length of the output record area required in the 
DFF program 
b. Decimal length of the Field Descriptor Table 
c. Decimal length of the 3270 output data stream 


6. Places the printer format in a work file (SWORK) on 
disk, then catalogs the printer format in an object 
library on disk. 


Printer/Display Layout Sheet 


The printer/display layout sheet is the same as that used 
for DFGR (Figure 8-2). The application programmer uses 
this form to plan the format and layout of the fields on the 
printer. The completed layout is then used as a guide to 
complete the printer control and field definition forms (see 
Figures 8-8 and 8-9). 


The layout is 132 positions per line, the maximum platen 
length. Other platen lengths used are 120 and 126 posi- 
tions per line. 


Printer Control Form 


The printer control form provides special information about 
the printer format which, in general, is unrelated to the 
fields being defined. One printer control form is required 
and must precede all field definition forms. (Both forms 
appear on the Printer Format Specifications sheet—see 
Figures 8-4 and 8-8.) 
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International Business Machines Corporation 





— 


Application 





| Completed by 


PRINTER CONTROL 





Printer 


Punching 
Instructions 


PRINTER FORMAT SPECIFICATIONS 


Graphic 


GX21-9238 
Printed in U.S.A. 






















Disk Storage Unit 
Z_ for Pritter Formats 
§& Print/No-print (P, N) 


= Di 


TUUTTT TTT TTT TTT TTT TTT TT 


(Reserved) 


Identification-Sequence 


21 2223 24 2526 27 28 20 30 3132 3334 3536 37 3839 4041 4243 44 45 4647 4849 50 5152 5354 5556 5758 59 60 61 6263 G4 65.66 67 6B 69 7071 72173 74 75 7677 7879 80) 


Figure 8-8. Printer Control Form is the First of Two Forms on the Printer Format Specifications Sheet 


Entries on the printer control form are as follows: 
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Form Type—Column 1 


The preprinted character H identifies this as the 
printer control form. 


Printer Format Name—Columns 2-7 


This entry is used to assign a unique name to a 
printer format. Entries in colurnns 2 and 3 are $Z. 
The remaining characters in the name can consist of 
any combination of alphabetic and/or numeric char- 
acters plus any of the characters $, #, or @. Blanks 
may not appear between characters in the name. The 


length of the name can be from three to six characters. 


All application programs using a particular printer 
format must refer to it by its assigned symbolic name, 
because each printer format is cataloged in the object 
library under its symbolic name. 


Printer Size—Column 8 


Enter a 71 or leave this column blank if the printer 
format is to be used with a 480-character printer. 


Enter a 2 in this column if the printer format is to 
be used with a 1920-character printer. 


If more fields are defined than can be displayed, an 
error message is issued; and all remaining field defini- 
tion forms are read but not processed. 


Platen Length—Column 9 


Enter a 1 in this column if the printer used has a 
120-character platen. 


Enter a.2 in this column if the printer has a 
126-character platen: 


Enter a 3 or leave this column blank if the printer has 
a 132-character platen. 


Line Length—Columns 10-12 


Enter in these columns the length of the line to be 
printed. Valid line length can be from 001 to the 
platen length specified (see column 9). A field can- 
not extend beyond the line length specified. 


Lines Per Page--Columns 13-14 


Enter the total number of lines (page length), from 
1 through 99, that can be printed on a single page. 
lf columns 13-14 are left blank, the default value 
is 66 lines per page. 


Multiple Pages—Column 15 


Enter an X in this column if the printer format re- 
quires more than one page. If this column is blank, 
all fields are printed on one page. Any field that has 
a /ine/position value less than the previous field 
specified is flagged with an error message, and the 
format is not built. If this column contains an X and 
a field has a /ine/position value less than the previous 
field specified, the field is placed on the next page at 
the /ine/position value given. Processing of the 
remaining field continues. 


Vertical Forms Feed—Column 16 


Enter an X in this column if a 3288 printer is used 
with the option to support the forms-feed function. 
Forms-feed is not used if this column is left blank. 


Note: The Katakana feature does not support vertical 
forms feed. 


Disk Storage Unit for Printer Formats—Columns 17-18 


Enter R1, F1, R2, or F2 to specify the location of 
the object library in which the printer format is to be 
stored. If columns 14 and 15 are blank, the printer 
format is stored on the disk from which the printer 
format generation routine was loaded. 


When CCP is executing, all printer formats must be 
stored on either the CCP program pack or the DSM 
system pack. 


Katakana Printer Format—Column 19 


Enter an X in this column if the format to be gener- 
ated is to be used on a Katakana printer. Leave this 
column blank for all other printers. Formats gener- 
ated for a Katakana printer should not be used on a 
non-Katakana printer because unpredictable results 
will occur. Non-Katakana formats should not be run 
on Katakana printers. 


Print/No-print—Column 20 

Enter P or leave this column blank if the initial 
format (not modified by an operation) is to be 
printed on the 3270 printer. 

Enter N if the initial format is not to be printed. 
(Reserved)—Columns 21-72 

These columns are reserved and are to be left blank. 
Identification-Sequence—Columns 73-80 

Enter any characters for sequential identification. 


These columns are ignored other than to be printed 
as part of the statement. 
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FIELD DEFINITION 
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Location 












































Figure 8-9. Field Definition Form on the Printer Format.Specifications Sheet 


Field Definition Form 


Refer to the printer/display layout sheet and the printer 
control form while completing the field definition form. 
Each field in the printer format must be specified on a field 
definition form. When defining fields using PFGR, do not 
allow space for defining and terminating attributes, as 
PFGR does not generate field defining or terminating attri- 
butes. The amount of printer buffer space specified need 
only be the length of the data and the printer control char- 
acters (NL, EM, FF). See Figures 8-4 and 8-9 for the loca- 
tion of the following items: 


a Form Type—Column 1 


The preprinted character L identifies this as a field 
definition form for the Printer Format Generator. 


Field Name—Columns 2-7 


Enter in these columns a unique field name that is 
from one to six characters in length. The first charac- 
ter must be alphabetic or a $, #, or @. The remaining 
characters can consist of any combination of alpha- 
betic and/or numeric characters plus any of the 
characters $, #, or @. Avoid assigning names begin- 
ning with @@@ because these characters identify 
special function requests. Avoid field names starting 
with D followed by five numeric characters when us- 
ing the field duplication function. Embedded blanks 
are not allowed. 
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Field Starting Location—Columns 8-12 


A line entry (two columns) and a position entry 
(three columns) define the leftmost character of the 
field. Allowable entries are limited by the printer 
size, line length, and lines per page entries (see 
columns 8, 10-12, and 13-14 of the printer control 
form). 


In the /ine field (columns 8-9), enter the number 
(01-99 not to exceed the value in the /ines per page 
field) of the line that the field is to occupy in the 
output. 


In the position field (columns 10-12), enter the 
number (001 to the value specified in the /ine length 
field) of the position on the line that the field is to 
occupy. 


The field starting locations must be consecutive and 
must not exceed the length of the printer buffer. 
Determine the number of characters used in the 
printer buffer as follows: 


@ If the vertical forms-feed order is not active (blank 
in column 16 of the printer control form), add 
the following to calculate the buffer required to 
build the format: 

a. Total length of all fields defined. 
b. Number of all unused positions on a line that 
precede the tast field in the line. 


c. One character for each new line (NL) order 
when building a format for a non-Katakana 
printer, or two characters for each NL order 
when building a Katakana format. An NL 
occurs each time that the last position in a line 
does not contain a character. Only the last line 
that contains a field and all previous lines are 
included in this count. If the last position in a 
line contains a character and the line length is 
equal to the platen length, the printer auto- 
matically advances to the next line and an NL 
is not required. 

cl. One character for an end-of-message (EM) 
order when building a format for a non-Kata- 
kana printer, or two characters for an EM order 
when building a format for a Katakana printer. 


@ If the vertical forms-feed order is active (an X in 
column 16 of the printer control statement), add 
the following to calculate the buffer required to 
fouild the format: 

a. Total length of all fields defined. 

b. Number of all unused positions that precede 
the last field in a line. Exclude line 01, position 
001, from this count on all but the first page 
of the format (this position is unusable after a 
forms-feed order). 

c. One character for each new line (NL) order. 

An NL occurs each time that the last position 
ina tine does not contain a character. Only 

the last line to contain a field on each page and 
all previous lines on that page are included in 
this count. If the last position in a line contains 
a character and the line length is equal to the 
platen length, the printer automatically advances 
to the next line and an NL is not required. 

d. One character for each page (excluding the 
last page) that does not contain any fields on 
the last line of that page. 

e. One character for an end-of-message (EM) 
order. 


Note: When a small print buffer is used (1 in 
column 8 of the printer control form), the preced- 
ing calculations must not exceed 480 characters, 
When a large printer buffer is used (2 in column 

8 of the printer control form), the preceding 
calculations must not exceed 1920 characters. 


ga Field Length—Columns 13-15 


The minimum field length is 1. The maximum field 
length is the line length value entered in columns 
10-12 of the printer control form. 


Data Source—Column 16 


Enter an E if data is provided at the initial printer 
format during execution by the application program. 
Enter a G if the data is supplied in columns 32-71. 
Enter an F if the data is supplied in columns 32-71 
and a Field Descriptor Table entry is not required for 
this field. Data in columns 32-71 is ignored if E is 
entered in column 16. If column 16 is left blank, G 
is assumed. 


Repeat Last Character—Column 17 


Enter an X in this column if the last character entered 
in columns 32-71 is to be repeated to the end of the 
field. For example, if 20 asterisks (*) are to be 
printed, define a field 20 characters long; place an 
asterisk in column 32; and enter an X in column 17. 
The result will be a field of 20 asterisks. 


Reserved—Columns 18-31 
These columns are reserved and must be left blank. 
Data—Columns 32-71 


Enter the data for the generation-defined fields. 
Data must not exceed the field length specified in 
columns 13-15. If the data exceeds 40 characters, 
place an X in column 72 and continue entering data 
in column 32 of the next line (leave columns 2-31 
blank). If an execution-defined field is specified (E 
in column 16), columns 32-71 are ignored. 


Continuation—Column 72 


If the data entry exceeds 40 characters, enter an X 
in column 72 and continue entering data in columns 
32-71 of the next line. No more than three continu- 
ation lines are allowed. 


/dentification-Sequence—Columns 73-80 
Enter any characters for sequential identification. 


These columns are ignored other than to be printed 
as part of the statement. 
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Printer Control on the Field Definition Statement 


A method of supplying forms-feed printer control is to 
request the generation of these orders on field definition 
statements. 


Notes: 

1. Multiple pages must be specified (an x in column 15 on 
the printer control! form) if printer control is used. 

2. The Katakana feature does not support vertical forms 
feed. 


To specify printer control (forms feed) on a field definition 
statement, enter the following: 


a Form Type—Column 1 


The preprinted character L identifies this as a field 
definition for the Printer Format Generator. 


| 2 | Field Name—Columns 2-7 


To indicate either a forms-feed order (for 3288 
printers with the Vertical Forms Control feature) or 
to generate multiple NL orders to advance the printer 
to line 01, position 001 of the next page, enter - 
@@@FF. 


Nove: \f a 3288 printer with the Vertical Forms 
Control feature is given the forms-feed order, the 
printer is advanced to line 01, position 002, of the 
next page. 


PFGR Line/Partial-Line Duplication 


PFGR supports a line/partial-line duplication feature to 
allow a defined field (the master) to be duplicated on 
following output lines. The master line must be defined 
first; the duplicated lines must be defined immediately 
following the master line definition and must be entered in 
ascending order. Any number of blank lines can be left 
between the master and duplicated lines on the output 
form. The duplication request is entered as follows: 


kl Form Type—Column 1 


The preprinted character L identifies this as a field 
definition for the Printer Format Generator. 


Field Name—Columns 2-7 


Enter @@@DP to indicate the duplication request. 
The master field must immediately precede this 
entry. This request causes the field(s) defined in the 
master field definition statement to be duplicated in 
a new location. 
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| 3 Field Starting Location—Columns 8-12 


A line entry (two columns) and a position entry 
(three columns) define the horizontal output line 
where the master line is to be duplicated and the 
position of the first character to be duplicated. 


In the /ine entry (columns 8-9), enter the output line 
number that is to contain the duplicate of the master. 
Line numbers must be in ascending order, though 
any number of blank lines can be left between the 
output lines. 


The position entry (columns 10-12), an optional 
entry, defines the first position of the master to be 
duplicated. If the position specified is not the start- 
ing position of the field within a line, duplication 
starts at the beginning of the next field. If the pos/- 
tion entry is left blank, duplication begins at position 
001, 


EX Field Length—Columns 13-15 


This entry, an optional entry, specifies the number 
of fields to be duplicated from the master. If no 
entry is made in these columns, all fields beginning 
at the point specified in the pos/tion entry are dupli- 
cated. If the number specified is greater than the 
number of master fields on the line, duplication 
begins with the first field specified and continues to 
the last field of the master. 


If the master is to be duplicated on a number of 
consecutive output lines, enter the character @ in 
column 13 and the number of times the line is to be 
duplicated on the output in columns 14 and 15. 


The remainder of the duplication statement must be left 
blank. 


Notes: 

1. If a duplication request statement contains both field 
definition statements and fields generated by a previous 
duplication statement, only those fields defined directly 
by field definition statements are duplicated. 

2. Field names are assigned to fields generated under the 
duplication process. Such names have the form 
Dilppp, where Itppp indicates the line and position loca- 
tions. Avoid defining other fields using this convention 
because duplicate field names could result. 


Example of a Format Written for the Printer Format 
Generator: Following is an example of a format written 
for the Printer Format Generator. The /ine and position 
values (columns 8-12) on the field definition statements in 
the example (part ) are the placement of each field on 
the page when printed on the 3270 printer (part 8 | ). 


When generation-defined data is specified (G in column 16), 


the data supplied in columns 32-71 for the length specified 
in columns 13-15 is printed on the 3270 printer. 


H$ZPFO21311L099X RL 


LB2 02010 186 CUSTOMER NUMBER - 
LB3 02029 ~6E 
LB4 04001 93GX * 
LB5 06010 106 ADDRESS — 


LB6 06020: 30E 
LB7 07020 30E 


LaaaDP 08 


When execution-time data is specified (E in column 16) 
and the Display Format Test routine (DFTR) is being run,: 
asterisks are placed in the field and printed. The DFTR- 
can be used for either printer or display formats. When 
execution-time data is used with the Display Format Con- 
trol routine, the data supplied during execution is placed 
in these fields. 


When the repeat-last-character function is specified, the 
last character supplied in columns 32-71 is repeated to 
the end of the field. 


The duplicate line function for PFGR is the same as the 
duplicate line function for DFGR (see Examples of Dupli- 
cation Function). The only variation is the method of 
supplying field names on the duplicated line statements: 
the position value is three characters instead of two 
characters. 


Jailoloioiciooioluoisiote dlojajaloioloiolaiolalalolojolojojoiotolojaloioloicieioioioioloiolaioksk GENERATED DUPLICATION FIELDS 


(DO802008020 30E 





LBS 09040 1L0E 


LB9 11010 116 QUANTITY — 
LBLO 8=61102 3E 

LBLL 13010 146 ITEM NUMBER 
B12 13024 2E 

LBL3 15001 93GX a 


$ZPFO2 PRINTER FORMAT INFORMATION 


Joloelokgtololoioiaioioiololaloiolololsioioisloiojoloiooloolotesiolosojsialoisbietelaoiofoo’ END OF GENERATED DUPLICATION FIELDS 


EXECUTION TIME DATA — OUTPUT AREA FORMAT — END POSITIONS FOR RPG PROGRAMS 








* FIELD FIELD END * FIELD FIELD END * FIELD FIELD END ae 
2 NAME LENGTH POSITION * NAME LENGTH POSITION * NAME LENGTH POSITION * 
ee — x ee eo aaa 
%* ~ OPCODE 004. 0004 * LENGTH 004 0008 % TMNAME 006 0014 = * 
*  $CPFO2 006 0020 * &B3 006 0026 »* Bé 030 0056 = * 
% BLO 003 0129 * «B12 002 O13 * 


LENGTH OF QUTPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR92* - 0131 OTHER — 0123 


INFORMATION FOR USE DURING CCP ASSIGNMENT STAGE 


THE DECIMAL LENGTH OF THE FIELD DESCRIPTOR TABLE IS 0112 
THE DECIMAL LENGTH OF THE OUTPUT TEXT IS 0213 


o CUSTOMER NUMBER — = saielekxei 


Aoksololojojaiololololaioloioioiiolelciojeiololojoiolnieiclojoiololojsioioiaisiolojaleloloisioloiotelciolalatoielorcialok loleslkofatclal os aolol color son ek Ho eR a a 1 0K 


ADDRESS — 2bisleeolooloiololsionioraioloiataiolokotatotot 
Jlolelololololsieiaiololololelojolotolalololololojalofojor 
Jelolcloelolajolojeiololorsiototoolataloloiataloiotok 

Jokgoloolaiototoke 


QUANTITY ~— “eter 
ITEM NUMBER — > 


2slatololajatoiolalaioiolojoloiojaioiolazsieiojaioiajojoloioiolololsjolol joo slo oiiolooioioloiclo tool aicolicloiolo glo iol total aol sei iso ol iotoko gona tok sok 
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OCL Considerations for the Printer Format Generator 


The following OCL statements are required when either 
single or multiple formats are built: 


// LOAD $CCPPF ,unit 


Ri 
F1 
R2 
F2 


// FILE NAME-$SWORK,UNIT- ,PACK-packid, 


RETAIN-S,TRACKS-2 


// RUN 


When reading from the system input device, be sure that 
the printer format statements immediately follow the RUN 
statement. A /* follows the printer format statements. 
The statements are read from the system input device and 
written into a $SOURCE file. If the printer format state- 
ments require more than five tracks of a file, define a 
$SOURCE file with an adequate number of tracks. Ifa 
$SOURCE file OCL statement is not specified, a 5-track 
$SOURCE file is automatically allocated on the unit from 
which $CCPF was loaded. 


When reading from the source library, specify a $SOURCE 
file with enough tracks to contain all the printer format 
statements in the source library entry. A COMPILE is also 
required with the following parameters: 

R1 
Fi 
R2 
F2 


// COMPILE SOURCE-name of source data,UNIT- 


where UNIT is the location of the source library. 


Notes: 

1. For multiple format builds in a single run, the input 
stream must not contain delimiters between the printer 
formats. Instead, the H in column 1 of the printer con- 
trol form indicates the start of another input. 

2. Enter an asterisk (*) in column 1 to identify a comment 
statement. Comments may be used to include notes on 
the listing produced by the Printer Format Generator 
routine. Comments can be placed anywhere in the for- 
mat build; however, on multiple format builds, all 
comments entered before the printer control form of 
the second or later format builds are printed with the 
previous format build. 
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Printer Format Generator Diagnostic Messages 


During its processing, the printer format generator (PFGR) 
diagnoses errors in the Printer Format Specifications and 
logs diagnostic messages on the system logging device. 
Refer to the CCP Messages Manual, GC21-5170, for a list 
of the diagnostic messages. 


Because the PFGR also calls the Overlay Linkage Editor 
to put the formats into the object library, it is possible 
to get Overlay Linkage Editor halts during PFGR processing. 


DISPLAY FORMAT CONTROL ROUTINE (DFCR) 


The display format control routine operates under CCP to 
support formatted displays (screen or printer), as generated 
by DFGR and PFGR, for the IBM 3270 Information Display 
System. 


Model 10 and Model 12 DFCR: The control routine is 
loaded along with the first application program that requires 
DFF. In addition to the usual user allocation and initiation 
tests, CCP must make sure there is enough storage for 
DFCR before the program can start. The DFCR and the 
output hold area(s) are loaded at either the upper or lower 
boundary of the user program area and remain in main 
storage until the last application program using DFF termin- 
ates. The space occupied by the DFCR will then be made 
available for other uses. 


Model 15 DFCR: The DFCR is loaded into the resident 
portion of CCP during Startup and remains resident in 
main storage throughout the CCP run. 


The facilities can best be described in terms of output and 
input operations. Figure 8-10 shows an example of the 
operations performed by DFCR. 


DFCR Functions for Output are: 


@ Automatically retrieves the printer or display format 
requested by the application program. 


@ Merges execution time data supplied by the application 
program with the 3270 data stream at the proper field 
location; checks numeric fields for negative values. 


@ If necessary, splits the 3270 data stream into blocks and 
sends each block separately to the 3270. See Hold Area 
for a discussion of blocking. 


@ Provides application programs with the capability of 
modifying (overriding) the attributes, data content, or 
both of any field currently at the display. It also 
allows the application program to receive input from 
only selected fields. 


@ Provides the Copy operation which can be used to 
transfer a printer or display format between devices 
attached to the same control unit. 


® Provides the Erase operation which can be used to 


clear all unprotected fields and reset the device for data 
entry for the terminal operator. 
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An application program running under CCP requests a particular format by issuing a Put Message operation, 
specifying the symbolic name of the format. (The symbolic name is defined in columns 2-7 of the display 
control form.) 


The Display Format Control Routine (DFCR) reads the requested format from the object library. (Format 
was placed in the object library by the Display Format Generator or the Printer Format Generator.) 


The first part, the field descriptor table, is read into an area appended to the user program. 
The second part, the 3270 data stream for this format, is read into the output hold area appended to the DFCR. 


The format is passed from the output hold area to CCP for transmission to the display station. 


Figure 8-10. DFCR Functions 
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DFCR Functions for Input are: 


@ Creates a data record area based on fields received, or not 
received, from the display format at the terminal. 


@ Pads alphameric data on the right with spaces; right- 
justifies data in numeric fields and pads it on the left 
with spaces. 


@ Examines numeric fields for negative values. 


3270 DISPLAY OPERATIONS 


Requests for 3270 display operations are like other CCP 
communications |/O requests; that is, each request is 

issued through the communication service subroutine (by 
means of a macro in Basic Assembler) and must be accom- 
panied by a parameter list and a record area. The parameter 
list contains information necessary for the operation 
requested as well as a location in which CCP will set a 
return code indicating the results of the operation. For 
certain operations, the programmer must supply additional 
information in the record area besides the terminal name 
and data, For example, when requesting that a display 
format be written to a 3270, the name of the display for- 
mat is given in the record area following the terminal name. 


See the sections for each language to determine such things 
as: the placement of op codes, return codes, input/output 
lengths, and symbolic terminal names. 


DFF operations are always in message mode (see index 
entry). Record and block mode operations are not valid 
when using DFF. 


Operation Considerations With DFF 


Copy, Erase, and Put Override are operations provided 
specifically for DFF users. These operations are described 
in detail in this section. Use of the Put Message operation 
to place the initial format on the screen or printer is also 
described. Considerations for using the remaining CCP 
operations under DFF are given in this section and under 
Operations in Chapter 2. See Examples at the end of this 
chapter for examples of using CCP operations under DFF, 


Put Message 


The Put Message is used to request that a particular printer 
or display format be retrieved from the object library and 
sent to the designated terminal. This operation is used to 
send either a complete new format or an overlay format to 
a terminal (see Display Concepts for Overlay Sereens). 


feo [= [men [eo 


One of the above values must be used depending upon the 
programming language. The name of the printer or display 
format to be sent to the terminal must appear in the first 
six positions of the record area immediately after the ter- 
minal name. If the name of the format is less than six 
characters in length, it must be left justified and padded 
with blanks, The output length must include the six-charac- 
ter format name. If there is no data to be added to the 
format (no fields defined as requiring execution time data), 
the output length is 20 (six for non-RPG SUBR92). 











If data is to be added to the format at execution time, that 
data should start in the first data position after the format 
name. The amount of space to be provided for each field 
must be equal to the length of each field as defined on the 
format description sheet. The order of the fields provided 
must be the same as the order that they were defined to 
DFGR or PFGR. The output length specified with the 
operation is determined by using the format generator 
printout for this format. Use the end position of the last 
output field for RPG SUBR92 (less 14 for all others) as 
your length (the format name is included in this end posi- 
tion). The result of the Put Message is controlled also by 
the display format itself. Functions controlled by the 
display format are: 


Positioning of the cursor, 


— Whether or not the display will be cleared before 
writing the requested display format. 


— Device operations as initiated by the WCC. 


— Printer control through new line and end-of-message 
orders, 


The Put Message is changed automatically to Put Block 


by the control routine if blocking is required. (Refer to 
Storage Areas — Output Hold Area.) 
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Program Request under Format Put Message 


The PRUF Put message is used to format the screen with 
data to be used by the next program requested from the 
designated terminal. The PRUF-Put override or PRUF- 
Put message operation normally is the last operation 
before releasing the terminal or going to end of job. 










Meaning 


0072 114 bi GB PRUF Put Message 


One of the above values must be used depending upon the 
programming language. The name of the format to be sent 
to the terminal must appear in the first six positions of the 
record area immediately after the terminal name. If the 
name of the format is less than six characters in length, it 
must be left justified and padded with blanks. The output 
length must include the six-character format name. If 

there is no data to be added to the format (no fields defined 
- as requiring execution time data), the output length is 20 
(six for non-RPG SUBR9Q2). 








As with the Put Message operation, DFF will automatically 
block this operation if blocking is required. See Example 
4 at the end of this chapter for more information on 

this operation. 


Put-No-Wait 


This operation is defaulted automatically by DFF to a Put 
Message operation. 


Dec Meaning 


54 Put-No-Wait 


Put Override 


The purpose of the Put Override operation is to (1) change 
the type, reposition the cursor, modify the data content, or 
any combination of these things for any fields defined in 
the format, or to (2) restructure the input record (only 
selected input fields are received). 





Operation Code 





eee 


Note: RPG II allows the Put Override to be combined 
with an Invite Input operation (see index entry Put with 
Invite Input). 


Additional Requirements _ 


® The format must have been previously sent to the 
printer or display by a Put Message or Copy operation. 


@ The output length specified by the user in the parameter 
list must define the exact length of the override list for 
RPG SUBR9Q2 (less 14 for all others), starting with the 
WCC and including all field information in the list. 

(Can be only the WCC, if desired.) 


@ ADFF numeric field with a negative numeric content 
must have the sign over the units position. Space must 
be allocated in the format for the sign. DFCR moves 
the sign from over the units position to a position after 
the data (see DATA in Numeric Fields). 

® Information for a Put Override must appear in the user’s 


output record area, Fields are to be defined in the same 
order as defined at generation time. 


Information Returned 
@ Return codes (see explanation in Appendix E): 
0 Successful 


9 Terminal offline 


-n Negative return codes (1/O errors) 


Function and Use of Put Override 


The Put Override allows the application programmer to 
change the field where the cursor is to be positioned, or to 
change the type, modify the data content, or do both for 
any field currently being displayed. Only the display is 
changed, not the display format in the object library or the 
field descriptor table in main storage. By specifying the 
appropriate WCC with the Put Override, the programmer 
controls clevice operations such as starting the printer, re- 
setting the keyboard, and sounding the alarm (see Selecting 
the WCC). 


The application programmer can also elect to receive input 
on the next input operation from the terminal from only 
those input, input/output, and SPD fields in the override 
list by specifying the appropriate WCC. The control routine 
checks the WCC. If the reset modified data tag bit is OFF 
in the WCC, the modified data tags for all fields are not 
changed and, on the next input request, data will be pro- 
vided for all input fields, output/input fields, and for SPD 
fields that would have been received normally. If the reset 
modified data tag bit is ON in the WCC, the modified data 
tags for all fields, protected or unprotected, are turned to 
OFF. On the next input request, data from only those 
input, output/input, and SPD fields specified in the override 
list will be passed to the application program. 


When selecting input fields using a Put Override, the reset 
modified data tag bit in the WCC must be ON (described 
previously). The user must be aware that this sets the modi- 
fied data tag OFF for Input types 1, 2, 3, 4, and 7, output/ 
input field types 1, 2, 3, 4, 7, and 8, and SPD field types 3 
and 4. Also, for the SPD fields, the designator (>) is not 
changed to the designator (?). If any of the selected input 
fields are one of these field types, the application pro- 
grammer should not leave the type entry for that field 
blank but should instead provide the type entry for that 
field as override information even though the field type is 
not to be changed. This sets the modified data tag ON as 
required by the definition of these field types. 


The format of the input record area, when selecting input 
fields, is determined by the order, and field Jength, of the 
fields as they are defined in the override list. The program 
logic must indicate the last output operation to the terminal 
and process the data on the next input from the terminal 
according to that indication. The layout of the input 
record area must be defined for each variation of input 
structure. Regardless of the input, the AlD character 
always precedes the fields in the user's input record area 
and should be examined by the application programmer 
before the field data is processed. 


Program Request under Format Put Override 


0872 2162 | BHGB | PRUF Put Override 


The PRUF Put Override functions just like the normal Put 
Override operation with the added feature of formatting 
the screen with the data to be passed to a following 
program. The PRUF-Put Override or the PRUF-Put 
message operation is normally the last operation issued be- 
fore releasing the terminal or going to end of job. 













The information in the output record area, shown in 
Figure 8-11, consists of: 


® Field Name. As defined in columns 1-6 of the field 
definition form. The name must be left justified and 
padded with blanks to a length of six characters. Use 
the same symbolic name as defined to PFGR or DFGR. 
Fields in an override list must be specified in the same 
order as during format generation. 


© Field Type. If the field type is to be changed, this entry 
must contain the number of the type wanted. Leave 
blank if type is not to be changed. Allowable changes 
are: 


Output Fields—all types are interchangeable. 

Input Fields—types 1, 2, 5, and 7 are interchangeable; 
types 3, 4, 6, and 8 are interchangeable. 
Output/Input Fields—types 1, 2, 5, 7 and 8 are inter- 
changeable; types 3, 4, and 6 are interchangeable. 

— SPD Fields—all types are interchangeable. 


® Cursor Position. AC entry positions the cursor in the 
first character position of this field. If the cursor is 
specified for more than one field, the last field with 
a C specified positions the cursor. A blank entry does 
not move the cursor. 
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@ Erase/Modify Data Indicator. Enter an M if there is ® Data. Only include this field if M is specified for modify 


override data provided in subsequent positions. Such a data indicator. The M is immediately followed by data 
change can be made in output, output/input, or SPD equal in length to the field length as defined during 
fields. A blank entry means data in the field is not to format generation time (length of SPD fields does not 
be changed. include designator character). If M is not specified for 

the modify data indicator, the next field name begins 
Enter an E if the data input or output/input field at in this position. 


the terminal is to be erased to nulls. The erase indicator 
is valid only for input or output/input field types. If 
the E indicator is used, the next override field name 
begins in column 17. 








(for other First field Next field 
than RPG ee ea 
SUBR92) Field name 

Wi a 

1 67 8 13 14 #15 16 170 —~em OO 

Symbolic eo] Ne Data is included only if the modify data 
terminal indicator equals M; otherwise, the next 
name field begins in this position 


Modify data indicator 
or erase indicator 








Write Cursor position 
control 
character Field type 
Field name 
(for RPG SUBR92) First field Next field 
SST EN’ 
L 
1 45 | 89 a 21 22 23 24 25 
Operation _l Data is included only if the modify data 
code indicator equals M; otherwise, the next 
field begins in this position 
Output —— 
length Modify data indicator 
or erase indicator 
Symbolic — 
terminal Cursor position 
name 
Field type 
Write = 
control Field name 
character 


Figure 8-11. User Output Area 
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The output length consists of: 
® One for the WCC 


@ Plus the sum of the following information for al/ fields 
to be overridden: 


— Six for the field name 

— Three (one space for each of the three possible entries 
for type, cursor, and modified data indicator) 

— Field data length as defined at generation time (if 
data is provided) 


@ An additional fourteen spaces if RPG SUBR9Q2 is used. 


Considerations 


@ With a Put Override operation, the application program- 
mer can select to receive input from only those input, 
output/input and SPD fields specified in the override 
list. The field names must appear in the same order as 
they were given during format generation. 


® To restore the display to its original condition, the 
application programmer could issue a Put Message or 
another Put Override. 


®@ The override list can consist of a WCC only, if desired, 
(for exarnple, to restore the keyboard). In this case, 
input received from the terminal may be affected 
(although there are no fields specified), if reset MDT is 
also ON in the WCC. A Put Override of the WCC should 
be used only to print the display currently on a 3275 on 
an attached 3284 Model 3 printer. 


®@ Anentry in a Put Override list may consist of a field 
name only, with blanks for type, cursor, and modify 
data indicator. In this case, if the WCC specifies reset 
MDT, then this field would be selected for input on the 
following input operations. If the WCC does not specify 
resetting of the MDT, this override entry is ignored and 
no 3270 text is generated. 


Example 7 


The structure of the record area should be as follows: 


= 


If RPG SUBR9Q2 is used, the op code must be given 
in positions 1-4 and the output length must be given 
in positions 5-8. 


2. The six-character symbolic name of the terminal. 


3. The WCC. This field is mandatory. The WCC can be 
determined by following the directions in Figure 8-6. 


4. For each field which is to be overridden, the following 
nine positions must be given or reserved in the output 
record area: 

a. Six positions for a field name (left justified) 

b. One position for type 

c. One position for cursor (C) 

d. One position to indicate modified data (M) 
or erase order (E) 


5. The modified data indicator of M means that data 
is to be provided. {f no data is to be provided (no 
M indicator) the record continues with the next 
symbolic field name. 


Example 2 


A primary use of the Put Override operation is interactive 
error detection/correction with input data being analyzed 
by the program logic. If any input fields are found to be 
in error, a Put Override operation is performed to the ter- 
minal with those fields in error displayed in intensified 
mode. Additionally, an error message can be displayed, 
the audible alarrm sounded, and the cursor positioned at 
the first field in error. The RPG II programming example 
in Figure 8-12 illustrates the logic necessary to perform 
these functions. 


The input fields are diagnosed in sequence, with the two 
arrays initialized to blanks and array index B advanced for 
each field. When an invalid input is diagnosed, the sub- 
routine ERROR is executed, with indicator 63 set on for 
numeric fields. The cursor is positioned at the first field 
in error under the control of indicator 58. 


When all the fields have been diagnosed, indicator 61 set 


on indicates that a Put Override operation should be 
performed, 
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Figure 8-12. Put Override Example 
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Selecting the WCC 


Figure 8-13 is provided to assist in selection of the Write 
Control Character (WCC). To use the figure, determine 
the characteristics of the output device and the operation 
to be performed, then select the code from the chart. For 
example, the write control code that restores the keyboard 
and sounds the alarm on a display but does not reset the 


MDTs is an F. 


Operation 


Resiore Keyboard 
(No for displays) 


<|2/< 
Flsie|a Reset MDTs 


Sound Alarm 


QO 
“a 


<|z2|< 
& 8 


< 
8 


@ 
7 


Fae 


Output Device 


Display or Printer 
NL/EM Control 
40-Character 
Print Line 


Print Line 


po ea 
pa tet ea 
free] SS) 
Pee] 0%! 
fk pal 
eee ofl 
| Ee [N 
| D | M | 
| . | $ | 
Pp é@ tt | 
| B | K | 
= ae] 
| H | Q | 
| 6 | & | 


Print Line 





This character is converted internally to hex 6A for a WCC 


by DFGR when generating a format, and by DFCR when 


using the WCC in a Put Override operation. 


Figure 8-13. Write Control Characters 
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Copy 


The purpose of the Copy operation is to transfer a format 
between devices attached to the same 3271 Control Unit. 
See Selecting the Copy Control Character in this chapter. 


Operation Code 


0042 2 | 6 | woe | Cony _ 2 | 6 | woe | Cony _ 


Additional Requirements 


The symbolic names of the terminal to receive the format 
(TO terminal) and the terminal to send the format (FROM 
terminal) appear in the output record area as follows: 


Not RPG SUBRQ2: 


| TO terminal FROM terminal ccc 


RPG SUBRQ2: 


| [TO terminal | |} TO terminal _| FROM terminal | ccc | 


[<< 8 9 ~<t— 14 15—-—— 20 21 


The Copy Control Character (CCC) is optional and, if 
present, appears in the first position after the FROM 
terminal name. For a discussion of CCC, see /BM 3270 
Information Display System Component Description, 
GA27-2749. A default CCC will be assumed if one is not 
given, 


The output length should be 20 (six for other than 
RPG SUBRQ2) if the default CCC is to be assumed, or 
21 (seven for other than RPG SUBR9Q2) if a CCC 

is provided. 


The FROM and TO terminals must be connected to the 
same 3271 control unit. A Put Message or a Copy 
operation must have been successfully issued to the 
FROM terminal prior to issuing a Copy operation. 
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This operation cannot be performed on a 3275. Data 
currently displayed on a 3275 screen can be printed on 

an attached 3286 Model III Printer using a Put Override 
with the proper WCC. Data can be simultaneously displayed 
on a 3275 screen and printed on a 3286 Model III Printer 
by using a Put Message. 


Information Returned 

Return codes (see explanation in Appendix E): 
0 Successful 
9 Terminal offline 


-n _— Negative return codes (!/O errors) 


Function and Use of Copy 


This operation allows a format to be transferred between 
two devices attached to the same 3271 Control Unit. The 
application programmer may choose to use this operation 
instead of a Put Message for performance reasons. The 
advantage of this operation is that line transmission time 
is reduced because only a few characters are sent on the 
BSCA line. 


Considerations 


@ When a complete format image is received by the TO 
terminal and an overlay format (see Display Concepts) 
was the last format sent to the FROM terminal, that 
overlay format will be the only part processed by the 
Display Format Facility. 


@ Default CCC for a model 1 terminal is X’5B’ (graphic 
character ‘$’): default CCC for a model 2 terminal is 
X‘7B' (graphic character ‘#’). 


@ Adisplay format can be locked (made incapable of 
being copied) by defining a protected field starting at 
line 1, position 2. DFGR will automatically place the 
attribute (specifying protected field) at line 1, position 
1. 


@ The output length for Copy does not include the 
“copy to” symbolic terminal name but does include 
the space for the “copy from” symbolic terminal 
name and, if given, the copy contro! character. 


@ if a Put Override with select input fields was previously 
issued to the FROM terminal, it will be assumed that the 
same operation was performed at the TO terminal. 


Example Indicator 36 signifies that the AID from the last input 
operation was an operator log request. The calculation 


The RPG I! example shown in Figure 8-14 illustrates the logic performs three exception output operations to acquire, 
coding logic that can be used when the 3284/3286 is used copy to, and release the printer designated as the log device. 

by various terminals and/or programs as a log device. In The return code should be checked after the Acquire opera- 

this example, the printer is first acquired, copied to, then tion and the Copy operation. 


released, then acquired by the next Copy operation sequence. 
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Figure 8-14. Example 3284/3286 Coding 
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Selecting the Copy Control Character 


Figure 8-15 is provided to assist in selection of the Copy 
Control Character (CCC). To use the figure, determine 
the characteristics of the output device and the operation 
to be performed, then select the code from the chart. For 
example, to copy the entire buffer of a display and to 
sound the alarm, the code is G. 


Notes: 

1. The default CCC for a Model 1 terminal is $ (hex 5B) 
and a Model 2 terminal is # (hex 7B). 

2. When copying a display format to a terminal and input 
is expected from the copy-to terminal, it is strongly 
recommended that either the entire buffer or the 
attributes and protected CCC be specified to enable 
DFGR to identify all input fields. 
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Output Device 


Operation Format 


Display or Printer 
NL/EM Control 
40-Character 
Print Line 
64-Character 
80-Character 
Print Line 


(No for displays) 
Print Line 


Copy Attributes 


” s 
Copy Attributes 
and Unprotec- 


ted Fields 


Yes 
Copy Attributes 


ce | Sound Alarm 
Pri 


and Protected 
Fields 


Copy Attributes | yes 
and All Fields 


(entire contents 
of buffer) 





1 This character is converted internally to hex 6A for a WCC by 
DFGR when generating a format, and DFCR when using the 
WCC ina Put Override operation. 


Figure 8-15. Copy Control! Characters 


Erase 


The purpose of the Erase operation is to clear the data 
portion of all unprotected fields in the current format. 


Operation Code 





Additional Requirements 


@ A Put Message or Copy operation must have been 
issued to this terminal prior to the Erase operation. 


@ The symbolic terminal name must be specified in the 
users output record area. 


® Output data length = 14 (or.0 if non-RPG SUBR9Q2). 


Information Returned 

@ Return codes (see explanation in Appendix E): 
0 Successful 
9 Terminal offline 


“ns negative return codes (1/O errors) 


Function and Use of Erase 


The Erase operation: 


®@ Clears the data portion of all unprotected fields to nulls 
(X‘00'). 


® Sets the modified data tag on all unprotected fields to 
off. 


@ Unlocks the keyboard. 
® Resets the AID byte. 


® Repositions the cursor to the first character location in 
the first unprotected field. 


If the entire display contains protected fields, the keyboard 
is unlocked, the AID is reset, and the cursor is positioned at 
line 1, position 1. 


Considerations 


@ An Erase operation is effective only if something has 
been placed on the display by a Put Message or Copy 
operation. When Erase is used, be aware that unprotected 
output/input fields containing data will have data erased 
and MDT tags set to OFF. It is suggested a Put Message 
be used to restore the display to its original condition if 
output/input fields are being used. 


Return Codes 


CCP return codes, including the special meaning of the data 
truncated return code under 3270 DFF, are described in 
Appendix E. 


If a negative return code is given for a Copy operation, 

Put Message operation, or Put Overrides operation with 
reset modified data tags, or if the CLEAR key exception 
return code is given for an input operation, DFCR treats 
the terminal as if no format were ever issued to it. Thus, 

if a negative return code is given for one of these operations 
(or CLEAR return code) and the next operation is a Get, 
the program is cancelled with a termination code of FF. 


Input Operations - Accept Input, Get, Stop Invite Input 


Input operations are used to request input data (message) 
from the terminal whose name is specified in the record 
area (or in the parameter array for RPG It). When using 
display format services, the input operation codes that 
require processing by DFCR are: 


Get 

Invite Input 
Accept Input 
Stop Invite Input 


The control routine moves data into the input areas if data 
was received successfully. For the manner in which fields 
are handled, see Field Concepts and Record Concepts. A 
Put Message or Copy operation must have been success- 
fully issued to the terminal prior to issuing one of these 
operations. 
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The structure of the input record area (beginning in position 
15 of the data area when using RPG SUBR92 or position 

7 for other programs) is given on the printout of the format 
generation, The record area must be long enough to contain 
the end position +14 (+6 for other than RPG SUBR92 use) 
specified in the format generation listing. The first 
character will be the AID character followed by data for 

all input, output/input and SPD fields, in the order defined 
during format generation. 


if a Put Override was previously issued to the terminal, and 
that operation specified select input fields (reset MDT in the 
WCC), then the input record area will contain the AID char- 
acter followed by data for all the input, output/input, and 
SPD fields whose names appeared in the last Put Override 
list. 


If a Put Override was not issued to the terminal, the maxi- 
mum expected input length you put in the fourth element 
of the parameter list or array should be the end position 
given for all uses, under /ength of input record area required 
in DFF program on the format generation printout. 


If a Put Override with select input fields was issued to the 
terminal, the maximum expected input length to be speci- 
fied in the parameter list or array must include one for the 
AID character plus the total data length of all input, out- 
put/input and SPD fields whose names appear in the over- 
ride list +14 (+6 for non-RPG SUBR92 use). 


If a maximum expected input length is given which is less 
than the actual length, a data truncated exception return 
code will be passed to the program. In this case, the trun- 
cated length reflects the full data length of all fields that 
could fit into the area as specified by the maximum expec- 
ted input length entry in the parameter list or array. Thus, 
complete fields are returned; no incomplete fields are re- 
turned as in non-DFF operations. 


Note: Program request data is processed by DFF if the 
program requested is a DFF PRUF program, and PRUF is 
active on the 3270 terminal at program request time. Only 
in this case is the AID character returned in the first posi- 
tion of the user’s area (See Chapter 2 for more information 
on PRUF). The effective input length field in the input 
record area as filled in by RPG SUBR92 shows the data 
length of all fields that can fit into the area plus the AID. 


!nvite Input 
Invite Input requires a previously issued Put Message or 


Copy operation. The maximum expected input length is 
disregarded by DFF for this operation. 
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Release Terminal 


This operation is used by the Display Format Control 
routine to maintain, by program, a list of terminals using 
DFF. 


USER PROGRAM RECORD AREA 


The size of the input and output record areas (or combined 
input/output record area) in programs using DFF is calcu- 
lated from information provided in the printed output of 
DFGR. Figures 8-16 and 8-17 show the printed output from | 
DFGR for two formats -- $ZOREN and $Z0009. The sizes 

of the record areas for programs using these formats would 

be calculated as follows: 


@ Size of the output record area (programs using RPG 
SUBR9Q2): 


$ZOREN $Z0009 


- Highest end position (trom 0020 0020 
DFGR printout) 
Total 0020 0020 


® Size of the output record area (programs not using 
RPG SUBRQ2): 


Highest end position (from 0020 0020 
DFGR printout) 
Less 14 positions used in 0014 0014 
SUBR9Q2 record area only 
Plus 6 positions for 0006 0006 
terminal name 

Total 0012 0012 


® Size of the input record area (programs using 
RPG SUBRQ2): 


Highest end position (from 0193 0547 
DFGR printout) 
Total 0193 0547 


© Size of the input record area (programs not using 
RPG SUBR92 SPECIAL): 


Highest end position (from 0193 0547 
DFGR printout) 
- Less 14 positions used in 0014 0014 
SUBR9Q2 record area only 
Plus 6 positions for 0006 0006 
terminal name 
Total 0185 0539 


$ZOREN DISPLAY FORMAT INFIRMATLION 


EXECUTION TIME DAIA - GUTPUT AREA FORMAT - END POSITIONS =72 RPS PROGRAMS 











* FIELD FIELD ENN * FIELD FIELD END * FIELD FIELD 
* NAME LENGTH POSITION * NAME LENGTH POSITION * NAME LENGTH 
Ree eee ween ee oo ceneee a 
* OPCODE 004 0994 * LENGTH 004 0008 *  TMNAME 006 
* $ZOREN 006 JO2uU * 

TNPUT AREA FORMAT = ENO POS ERLONS: FOR RPG PROGRAMS 
* FIELD FIELD END * FLEELD FIELD END * FIELD FIELD 
* NAME LENGTH POSITION * NAME POSITION * NAME LENGTH 
Bo eeeeR wee eee =H --- = wo sen ene aa eec ees H  ceeee- 0 HHH 
* RTCODE 004 0004 * LENGTH 004 0008 * THNANE 006 
* - AlD- 001 OOLS * = CUSNO 006 go2k * SNAME 022 
* SADORI 022 0065 * SADORZ 022 0087 * SADDRI 022 
* QTYL 004 O1L3 * ITEMNL 008 o1aL * aTy2 004 
* LTEMN2 008 0133 * QTy3 004 0137 * TTEMN3 008 
* QTyY4 004 OL149 * ITEMN4 008 0157 * QTys 004 
* LTEMNS 008 0169 * QTY6 004 0173 * ITEMN6 008 
* Qty? 004 0185 * I[TEMN7 008 0193 * 


LENGTH OF GUTPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR92* - 0020 OTHER ~ 6012 


LENGTH OF [NPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR9O2* - O193 OTHER - 0185 


INFORMATION FOR USE DURING: COP ASSIGNMENT STAGE 


THE DECIMAL LENGTH OF THE FIELD DESCRIPTOR TABLE 158 1150 
THE DECIMAL LENGTH OF THE OUTPUT TEXT IS 1146 
THE DECIMAL LENGTH OF THE INPUT TEXT 1S 0240 


Figure 8-16. Display Format Generation (SZOREN) 


EXECUTIGN TIME DATA — GUIPUT AREA FORMAT = END POSITIONS FOR RPG PROGRAMS 


* FIELD FIELD END * FIELD FIELO END * FIELD FIELO 
* NAME LENGTH POSITION * NAME LENGTH POSITEON * NAME DENGAE 
Roometer eee a a ea neew es Hwee ee 
* OPCODE 004 0004 * LENGTH 004 0008 * TMNAME 906 

* $Z0009 006 0020 * 

INPUT AREA FORMAT - END POSITIONS FOR RPG PROGRAMS 

* FIELD FIELD END * FIELD FIELO ENO * FIELD FIELO 
* NAME LENGTH POSITIGN * NAME LENGTH POSITION * NAME LENGTH 
* ------ ee een wee enn KO nae e ne =----- 
* RTCODE 004 0004 * LENGTH 004 0008 * TMNAME 006 

* - AID- ool o0Ls * NAMED 020 0035 * = =NAMER 020 

* FIRST# 038 0093 * SECONa 038 0131 & THIRDE 038 

* FORTH 038 0207 * FIFTHR 038 0245 * SIXTHa 038 

* ONE 044 0327 * TWO 044 O371 * THREE 044 

* FOUR 044 0459 * FIVE 044 0503 * SIX 044 


LENGTH OF GUTPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR9OZ* = 0020 NTHER - 0012 


LENGTH OF INPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR92* ~ 0547 NTHER - 0539 


TNEQRMATTON FOR USE DURING CCP Sos tGNneyE STAGE 


THE DECIMAL LENGTH UF THE FIELD DESCRIPTOR TABLE [5 0395 
THE OECIMAL LENGTH OF THE OUTPUT TEXT IS 0463 
THE DECEMAL LENGTH OF THE ENPUT TEXT IS 0579 


Figure 8-17. Display Format Generation ($Z0009) 
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END 
POSITION 


END 
POSITION 
0014 
0043 
0109 
0125 
0145 
OL6L 
0181 


END 
POSITION 


END 
POSITION 
0014 
0055 
0169 
0283 
0415 
0547 


ee H 


eee HH RH 


eee 


RRR ES 
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A program using both of these formats could use a single 
input record area and a single output record area. The 
size of each would be equal to the size required for the 
larger format. In this case, the size of the output area 
would be 12 for programs not using RPG SUBR92 or 
20 for programs using RPG SUBR9Q2. The size of the 
input record area would be 539 for programs not using 
RPG SUBR9Q2 or 547 for programs using RPG SUBR92. 


The output record area in these two examples allows for 
only the format name. An additional consideration for a 
larger size output ‘record would be if the Put Override opera- 
tion is issued by the program or if the program provides 
output data to display format fields during program execu- 
tion. The output record area would then need to be large 
enough for the Put Overrides list created during program 
execution or the total of the output fields, (value under 
heading /ength of output record area required in DFF 
program from DFGR printout) whichever is larger. 


The program could also use a single combined input/output 
record area. The combined record area (created in RPG 
when SUBR9Q2 file is used) would need to be as large as 

the larger of the input or output record areas. 


DISPLAY CONCEPTS 


New Screens 


The Put Message is used to request that a particular dis- 
play format be retrieved from the object library and written 
to the terminal. If the format is already at one terminal, 

a Copy operation can be used to duplicate the format from 
the first terminal to a second terminal attached to the same 
3271 control unit. (Note: The format cannot be copied 

if a protected field starts in line 1, position 2.) 


Overlay Screens 


Overlay screens are useful when only a portion of the screen 
is subject to change. 


When multiple display formats are written to the same dis- 
play, the integrity of the displayed data is the user’s respon- 
sibility. The following must be considered if the user places 
a second format over a part of a format already being dis- 
played without specifying ‘clear before writing’ on the dis- 
play control form. 
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1. MDT should be set to OFF for all 3. Entire fields or groups of fields should 

fields on Format 1 when Format 2 be overlaid to prevent residual data 

is placed over Format 1. from appearing between fields in the 
overlay format. Also, residual data 
following an SPD field in the overlay 
format may be transmitted along with 
the data for the SPD field during an input 
operation. This can cause data for other 
fields in the overlay screen to be lost. 


4. When using overlay screens, it is 
important that the terminal 
operator does not key into a field 
which belongs to a previous format. 
This could cause data for the fields 
in the overlay screen to be lost. 


5. The overlay format need not define 
complete lines of data. An overlay 
format can define fields between 
fields of an existing format. It is 
important, however, that fields of an 
overlay format and their defining 
and delimiting attributes do not 
partially overlay an existing field 
or are not placed within the area 
of an existing field. Overlay fields 
should either be placed in an unde- 
fined area or should completely 
overlay existing fields. 





This is the original format 


overlays the first format 





2. The control routine provides 
support for only the last 
format placed on the display. 
Only those input fields defined 
by the last display format will 
be accepted. All other field 
data will be ignored. 
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DFF, CCP CONSIDERATIONS 


Assignment Control Statements 


During the assignment stage of CCP (see CCP System 
Reference Manual), the user must define those terminals 
which, on a program basis, require DFF support. The 
assignment control statements affected and the informa- 
tion to be specified are as follows: 


SYSTEM statement — For DFF, a parameter on this state- 
ment identifies the disk unit and object library containing 
the display or printer formats. 


TERMATTR statement —This statement defines terminal 
attributes. On this statement, the user specifies whether 

or not DFF will be used with all terminals referencing this 
terminal attributes set. Under Model 10 and Model 12 CCP, 
the BLKL parameter is used to define the size of the output 
hold area (in main storage). The output hold area is used to 
prepare the 3270 data stream for output operations. A 
separate hold area is supported for each BSCA line. 


PROGRAM statement — This statement defines the logical 
structure and resource requirements of an application 
program. When using the Display Format Facility, the 
information required on a program basis is as follows: 


@ The maximum number of terminals, using the Display 
Format Facility, allocated concurrently to the appli- 
cation program. 


@ The maximum number of display or printer formats the 
program will use. 


@ The size of the largest. field descriptor table used with this 
program. The character length of the field descriptor 
table is printed by the Format Generation programs 
(DFGR and PFGR) for each format generated. 
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Storage Areas 


Output Hold Area—Model 10 and Model 12 CCP 


One output hold area for each BSCA line will be appended 
to the control routine to hold the 3270 data stream for 
output operations. When using Put Message or when 
overriding the attributes and/or contents of fields currently 
being displayed (see Put Overrides under 3270 Display 
Operations) this area is used by the control routine to 
build a data stream based on the execution time data or 
the override information in the output record area of the 
application program. 


The sizes of the output hold areas for each BSCA line need 
not be the same. Each may be the minimum of 256 bytes 
or as much larger (by multiples of 256 bytes) as needed 

up to the size of the output text of the largest display or 
printer format that uses this set. The size of the hold areas 
are determined by the BLKL parameter of the TERMATTR 
statement of the assignment set under which the program 
will execute. 


If the assigned hold area space is less than the size of the 
output text of the largest display or printer format, the 
control routine automatically splits the data stream into 
output blocks and sends each block separately. If the con- 
trol routine is to perform blocking, the hold area must. 
contain at least 512 bytes in order to accommodate one 


.256-byte block plus information that cannot be sent in the 


current block. The user should be aware that if he uses 
blocking to achieve core economy, it will probably result 
in less efficient use of the BSCA line if the line has a high 
rate of activity. 


Output Hold Area -- Model 15 CCP 


The output hold area is allocated dynamically by the CCP 
from the TP buffer area. The size of the output hold area 
is determined by the CCP based on the length of the output 
text of the format for each particular user program opera- 
tion. There may be, at most, two output hold areas 
allocated at one time, one for each BSCA line. 


TP Buffer 


Get, Invite Input, and (under Model 15 CCP) Put operations 
are not executed under DFF until TP buffer space is 
available. In calculating TP buffer area size at assignment 
time, the user should consider Invite Input, Get, and (under 
Model 15 CCP) Put operations that require DFF. See 

TP Buffer (dynamic) in CCP System Reference Manual 

for information on estimating the size of this area. 


User Program Storage Considerations 


In order for DFF to support multiple application programs 
concurrently, a storage area is appended to each application 
program when the program is loaded. The size and contents 
of this area are determined at assignment time. 


The storage area contains a fixed constant area plus a 
variable area depending upon the following: 


@ Maximum number of 3270 terminals the program can 
service concurrently. (Take into account the maximum 
number of requesting terminals and program selected 
terminals that can be serviced at one time.) 


@ Number of display or printer formats used 


@ Length of the longest field descriptor table given on the 
PROGRAM statement. 


The user must specify on the PROGRAM statement.-the 
size of the largest field descriptor table (information pro- 
vided by the display or printer format generator). A 
particular field descriptor table remains in the storage area 
appended to the application program until an output or 
input request requires a different format. On output, the 
table identifies those fields to be supplied data by the user’s 
output record area and also supports overrides to a field 
within the display. On input, the table aids in constructing 
the input record area from data received from a terminal. 
For storage size estimates, refer to CCP System Reference 
Manual. 


Terminal Operator Actions 
Keys 


See Operator’s Guide to /BM 3270 Information Display 
Systems, GA27-2742 for description of all 3270 keys and 
their actions. 

Use of keys with DFF: 

Key Situation/Resulting Action 

ENTER When the operator completes an 
operation and presses ENTER, the 
fields with MDT-ON are read auto- 
matically in response to a poll request 
from CCP. 

CLEAR A 07 return code is returned to the 
application program when the operator 
of a terminal presses the CLEAR key 
(returned on the next input operation). 
An AID character indicating CLEAR 

is never returned to the user program, 
whether or not the program uses DFF. 
The 07 return code is given to the pro- 
gram if the terminal operator resumes 
communication with the application 
program after data mode escape. 


Program Attention When the operator presses any one of 
keys—ENTER , these keys, the terminal responds to an 
all Program input request from the system and the 
Function (PF) Attention Identification (AID) char- 
keys, and the acter is generated (to identify which 
Program Access key was pressed). The AID is the 
(PA) keys first field in the input record. IfaPA 
key is pressed, only the AID character 
appears in the input record area, no data. 


If selector pen attention is caused by 
selection of an SPD field, each field that 
has the modified data tag ON will have 
a greater than (>) sign in the leftmost 
position of the field in the record area 
and the remainder of the field will be 
blank. 
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Key 


Character 
oriented keys 


Field 
oriented Keys 


ERASE INPUT 


ERASE EOF 
End of Field key 
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Situation/Resulting Action 


A cluster of four keys (located on 

the right of the keyboard) move the 
cursor one location at a time. These 
keys are:{(up), | (down)-(right), and 
~—(left), The cursor may be moved 
into any character location, including 
unprotected and protected alphameric 
character and attribute character 
locations. All four keys have typa- 
matic operation (keep repeating when 
key is held down); all four are capable 
of causing the cursor to ‘wrap’. 


Four keys that move the cursor to the 
first position in a field. These are —>+| 
(Tab), }+— (Backtab), -—(New Line) 
and the SKIP key. The tab key moves 
the cursor to the first character 
location of the next unprotected data 
field. If the cursor is located in other 
than the first location of an unpro- 
tected data field, the Backtab key 
causes the cursor to move to the first 
character location of that field. If 

the cursor is already located in the 
first position of a protected field, 

the cursor moves to the first alpha- 
meric character location of the first 
preceding unprotected data field. The 
New Line key moves the cursor to the 
first unprotected character location 
of the next line. The SKIP key is on 
the Data Entry Keyboard only and 
performs the same functions as the 
Tab Key. 


This key clears all unprotected fields 
to nulls and repositions the cursor to 
the first unprotected character location 
on the screen. It also resets all modi- 
fied data tags associated with unpro- 
tected data fields. 


1f the cursor is located in an alpha- 
meric character location in an unpro- 
tected data field, this key clears the 
position occupied by the cursor and 
all remaining character positions in 
that field. The cursor does not move. 
!f this key is pressed when the cursor 
is located in a protected field, it dis- 
ables the keyboard and no character 
locations are cleared. 


Key Situation/Resulting Action 
FIELDMARK  __ This key provides a means of informing 
the application program of the end of 
a field in an unformatted display. If 

the key is used in entering data, no 

special handling is provided when 

using DFF. 
DUP This key provides a unique character 
code to be entered into the display 
buffer and a standard Tab key opera- 
tion to be performed. The DUP 
character provides a means of in- 
forming the application program that 
a “duplicate” operation is indicated 
for the rest of the field in which it is 
located. If key is used in entering 
data, no special handling is provided 
when using DFF. 


Operator Identification Card Reader 


The Operator Identification Card Reader is a special feature 
for attachment to a 3277 or 3275 Display Station. It 

reads a small magnetic card encoded with a unique identi- 
fication number. When the card is placed into a reader, 

the text on the card is read into the display buffer. For 

the card read operation, the cursor must be positioned at 
the first character location of the input field. The field 
should be an unprotected alphameric field. The AID is set 
to indicate the operator Identification Card Reader. 


The field length should always be the length of the text 
plus three. The alphameric data which will be presented 
to the application program consists of text, an End of 
Record (EOR) or End of Inquiry (EO!) character, the 
L.RC character, and one-blank. 


This is the field | EORor EO! | LAC | Blank 


emcee ee 


There is a hardware-generated attribute character entered 
automatically at the location of the cursor. This attribute 
character must be removed by the application program if 
this field is to be re-used. This can be accomplished by 
issuing either a Put Message or Put Override operation. 


DISPLAY FORMAT TEST ROUTINE ($CCPDT) 


$CCPDT is a stand-alone program which displays DFF 
formats on an IBM 3270 Information Display System. 
SCCPDT operates under the IBM System/3 Models 10, 12,. 
and 15. Communication between $CCPDT and the 3270 
is maintained using the multitine/multipoint (MLMP) 
binary synchronous communications (BSC) data link. 


$CCPDT, shown in Figure 8-19, uses the formats generated 
by the Display Format Generator routine (DFGR) or the 
Printer Format Generator routine (PFGR). The formats 
must be in the object library of the program pack from 
which $CCPDT is loaded. 


For Model 10 and Model 12, $CCPDT will use SYSIN as 
the input device. When $CCPDT is loaded the following 
option menu will be logged on SYSLOG: 


OPTION MENU 

A. SEND FORMAT TO TERMINAL 

B. READ FORMAT FROM TERMINAL AND PRINT IT 

C. GO TO EOJ 

D. SEND FORMAT TO TERMINAL, POLL, PRINT INPUT 

E. SEND FORMAT TO SYSTEM PRINTER 

ENTER ALL. OPTIONS DESIRED THROUGH SYSIN IN ANY ONE OF TWO FORMS BELOW 
O FFFFFF PPPP AAAA 

O FFFFFF * 


For Model 15, $CCPDT will use the console as the input 
device. An option menu will appear on the screen describ- 
ing each option. The input data may be entered starting 
at the cursor position. 


Ae SEND FORMAT TO TERMINAL 

Be. READ FORMAT FROM TERM.,yAND PRINT IT 
C. GO TO EOJ 

De. SEND FORMAT TO TERMe»POLL,PRINT INPUT 
Ee SEND FORMAT TO SYSTEM PRINTER 

14)0 FFFFFF PPPP AAAA 2)0 FFFFFF * 


t 


Cursor 
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$CCPDT provides the user with two forms of input records 
and five options: 


1. 


O FFFFFF PPPP AAAA 
where: 


O = A,B,C, D, or E (these options are described 
later in this chapter) 

F = Format name, which must begin with the 
characters $Z. The name must be at least 
three characters long but not more than six 
characters long. 

P = Poll characters (EBCDIC or ASCII characters) 
Enter immediately following the first blank 
after the format name. 

A = Address characters (EBCDIC or ASCII 
characters) 


O FFFFFF * 

where: 
QO = A,B,C, D, or E (these options are described 

later in this chapter) 

F = Format name, which must begin with the 
characters $Z. The name must be at least 
three characters long but not more than six 
characters long. 

= Last specified poll and address characters 
(see note). Enter immediately following 
the first blank after the format name. 


Note: \f the poll and address characters are not specified, 
$CCPDT will use the last previous specified poll and 
address character. In this way the user can send multiple 
formats to the same terminal. If the user does not specify 
the poll and address characters at least once, $CCPDT 
will default to the following characters: 


Poll characters = bbWK (40404040) 
Address characters = -- (60604040) 
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Options 


A. 


Send Format to Terminal 


$CCPDT reads the selected format from the program 
pack. The format is then transmitted to a terminal. 
This option allows the user to view the format. 

This option does not allow input or output data to 
be received or transmitted. 


Read Format from Terminal and Print (t 


This option allows the user to test for invalid 
characters within the text stream. $CCPDT reads 
the entire format from the terminal (read buffer) 
and prints it. The user should compare the format 
on the terminal and the data portion (text stream) 
of the format printed. (See Figure 8-14 for example 
of printout.) 


Go to End of Job 


This option should be entered after the user has 
entered all other options to be used. $CCPDT will 
then go to end of job. 


Send Format to Terminal, Poll for Input and Print 
the Inout Data Received 


$CCPDT sends the format to the terminal and polls 
the terminal for input. The user enters data on the 
terminal keyboard. When attention is requested by 
the terminal operator by pressing either the ENTER, 
PA or PF key, $CCPDT receives the modified data 
and prints it on the system printer. This is a means 
of verifying the modified data transmitted to 
$CCPDT or what the text stream would look like 

if sent to anon-DFF application program. (See 
Figure 8-14 for example.) 


Send Format to System Printer 


$CCPDT reads the selected format from the program 
pack and prints the entire format on the system 
printer, This allows the user to view the 3270 text 
stream and provides a copy for documentation. 

(See Figure 8-14 for example of printout.) 










SYSLOG 
or 
Console CRT 


SYSIN 


_ Control flow > 
Dataflow >> 


$CCPDT prints/displays the options 
menu on the SYSLOG device. 


© $CCPDT reads an option from SYSIN. 


$CCPDT 





System 
Printer 










Object 
Library 
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$CCPDT reads the format name specified on the option 
record from the object library of the program pack. 


0 $CCPDT sends the format to the terminal. 


sends modified data from the format to the 


a $CCPDT sends the format to the system printer, or 


system printer. 


Figure 8-19. $CCPDT Functions 
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3270 Display System 


[ Address Text of Format in Hex Text of Format in Character | 





SZRPLO 

0000 27F5C332 3211C604 1060C3F4 € 2E30ED4 
OOlS FE310E85C S5C5C5CSC SCLIC660) ILNé6CN506 
0030 CS5LIC8F4 1060C3E4 E2E306D4 C€5N94005 
0048 SC5CSC5C SC5C5C5C SC5SC5C5C SC 5C5C5C 
0060 NM41C060F2 C8C9N7T4C E€3N61148 EALDE 85C 
oors scscscsc SCS5C5C5C SC5CSC5C SCLI4FC4 
0090 D64BL14F OSLDESSC SC5C5C5C SC5C5C1L 
OOAB O6D540C6H C9N3C511 DIE41D60 CSEICSD4 
ooco F3LTESSC SCSCSC5C SCSCSCSC 5C5C5C 5C 


Figure 8-14. Example of $CCPDT Format Printout 


$CCPDT Considerations 


Any format that the user wants to test must be in the 
program pack’s object library. Before a format is sent to 
a terminal or the printer it is scanned for nulls (00). In 
fields within formats defined as having execution time 
data containing nulls, the nulls are replaced by asterisks. 
Also in overlay formats with input fields containing nulls, 
these nulls are replaced by asterisks. Since nulls do not 
appear on the terminal, by replacing the nulls with 
asterisks, the user is able to see the null fields. 


OCL Statements 


An initialized MLTERFIL must be on F1, for logging 
contro! station terminal error statistics. The OCL required 
to initialized MLTERFIL is: 


// LOAD $$BSFI,unit 

// FILE NAME-MLTERFIL,UNIT-F1,PACK-pack, 
TRACKS-1,LOCATION-track number (optional), 
RETAIN-P 

// RUN 


The following OCL is required to run $CCPDT: 


// LOAD $CCPDT,unit 
[// BSCA LINE-2] _ see notes 
// RUN 


Notes: 

1. $CCPDT uses BSCA-1; if the user wants to use the 
BSCA LINE-2 instead of BSCA LINE-1, include the 
optional BSCA LINE-2 statement in the OCL. No 
recompilation of the program is required. 

2. For Model 8 using the ICA or local display adapter, the 
user must enter the BSCA LINE-2 OCL statement. 
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C5064005 06481106 5C 
E£3400605 40C6C9N3 
C1D4C51L COC3LDES 
§C5C5C5C SC5C1L148 
SC5C5C5C SC5C5C5C 
1D60C9E3 C5N44005 
4F5D1D6C 05065340 OC. LL Vue eeeee fN0T 
4CC4C5E2 C34R11N1 
SC5C5C5C S5C5C5C BOVE ORS RD 


FM -CUSTOMER NO. F 
T Y#eeeee FO ZNOT ON FIL 
— H4 -CUSTCMER NAME IC Y 
SOI IE ER RE, 
M -SHTP TC oT Y #8etk oe 
eeeeRe eee OT) -TTEM ON 


ON FILE Ju -ITEM CESC. J 


Display Format Test Routine Diagnostic Messages 


During processing, DFTR checks completion codes, status 
of terminals, and the various types of program intervention. 
Messages stating the reason the completion code was given, 
the status of terminals, and the type of program inter- 
vention received are logged on the system printer. For 

the DFTR diagnostic messages, see the CCP Messages 
Manual, GC21-5170. 


FORMAT FIND ROUTINE (5704-SC2 Only) 


The format find routine (CCPFMT) makes formats that 
have been created or modified by DFGR or PFGR in 
another partition, available to programs in the current 
assignment set. The routine is executed under CCP and 
performs the following functions: 


@ Places the current object library C/S (cylinder/sector) 
location of the format into the format index in 
$CCPFILE. 


® Updates the DFFSFDT value of the PROGRAM 
assignment statement. 


To use CCPFMT, make the following entries in the 
assignment set: 


// TERMATTR ATTRID-04,DATAFORM-MESSAGE, 
DFF3270-NO 
// PROGRAM NAME-CCPFMT,NEVEREND-YES, 
ENDMSG-NO 


The routine is invoked from either the system operator’s 
console or a command terminal. For additional informa- 
tion on the use of CCPFMT, refer to the Model 15 CCP 
System Operator's Guide, GC21-7619. 


Note: When CCPFMT is included in an assignment set, 
ATTRID-04 is reserved for format find. 


EXAMPLES 


Example 1—-DFF Formatting Example 


Problem: Design a display format to be used on the 3270 
display with an order entry program. Make the format usable 
with any programming language available under CCP. 


Solution: Plan the format by laying out fields on a display 
layout sheet. This then serves as a visual guide in filling 
out the field definition forms. 








IBM (nternational Business Machines Corporation DISPLAY FORMAT SPECI FICATIONS ee vie 
ses: ORDER ENTRY Completed by | Punching cron Page } = 





DISPLAY CONTROL 

































































z 
=| ‘ PRINTER CONTROL 
Field Namo |A}E] [SIR] <2 . 
Display for Initial cle} jefe} 55 < 
Name Cursor Position [a] e| | sha! ot § 
as] [gla| £2] = 
e zo g) a2] & 8 8 8 § $s 3 5 § £ 
5 aslels{ze2| E |e) 3] 2 | 3 si2|3]2}3 213 Sle| 3 = 
é alolslaelas| = | 5) 8) 5)8 15/28) 5)/ 8) 5] 8 S18 &j)5] 8]: 8] tdentification- Sequence 
11323456 7 8 9 10 11 1213]14/15 17]18/19 20/21 22 23/24 25/26 27/28 29/30 31 32 3: 34 36/36 37/38 39/40 41/42 43/44 4: 146 47148 49150 51 1162 6: 64 65/66 67 72|73 74 75 76 77 787980 
eSiziolRENChIsINiol ely] kl IR] TTT TT LET CT [| LUT T IT 
— , L 
Use to Disk unit where DFGR will place format into the object tibrary 
catalog 
format in Format is designed for 3270 display device. 
object library, Entry is ignored because there is an entry in column 17 
(first two Clear before writing 
characters 1920-character display 
are $Z). 
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GX21-9174. 
Printed in U.S.A. 


Printer /Display Layout "ORDER ENTRY. 
POSITION hw done 3-2-7 
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KEY ASSIGNMENTS 
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Shaded boxes indicate defining attribute positions. 


[J,Open boxes indicate trailing attribute positions. 
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Note: The large letters identify a portion of the display 
screen with a segment of the field definition information 
as it appears on the field definition forms and on the listing. 


This heading is a type 1 output field which means it 
is to be displayed at normal intensity on the screen. 


The entry on line 2 position 3 (under customer number) 
is a type 3 input field which means that it is a 
numeric field to be displayed at normal intensity. 


The entry on line 2 position 21 (under customer name) 
is a type 1 output field which means that it is displayed 
at normal intensity. 


The entry on line 2 position 46 (under ship to) is a 
type 1 output/input field. This entry is examined by 
the terminal operator and changed if necessary. 


Line 07 contains headings (type 1 output fields with 
normal intensity), The items in the quantity column 
are type 3 (numeric) while the item numbers are 
type 1 input (alphameric). Automatic skip causes 
the cursor to move to the next quantity entry. 


The fields in the rest of the line are defined as type 1 
output/input fields. Note that there is:a G in the 
data source column indicating information is pro- 
vided at generation time yet no entries appear in 
colurnns 32-71. All output and output/input fields 
have been described as being generation-defined with 
no eritries made in columns 32-71 because data will 
be provided using a Put Override during execution 
time. 


Ga Display line 22 contains visible headings (type 1 output 
' fields) and fields into which data can be placed by 
using Put Overrides at execution time (type 1 
output fields). 


Display line 24 initially contains a series of type 5 
output fields. Any one of these fields can be changed 
at execution time by the application program. They 
could, for example, be changed to displayed fields 
with high intensity. 


The display control form is used to describe the format in 
such a way that it can be properly stored and retrieved. 


All the information on the display control and field defini- 
tion forms is transferred to cards and used as input to the 
display format generator. 


Generation results include: 


1. The display format consisting of the field descriptor 
table and the 3270, data stream with control infor- 
mation are entered into the object library under the 
symbolic format name. 


2. Printout information: 


. Printout of the specification forms. 

. Log of diagnostic error messages. 

. Sequential list of output fields. 

. Input data fields and their order of appearance 
in the input record area. / 

e. The decimal length of the field descriptor table. 

f. The decimal length of the 3270 output data 

stream. 
g. The decimal length of the 3270 input data 
stream. 


E3fG) 
aon @ 
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FIELD DEFINITION 
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Display line 1 contains a visible heading. 
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An X in column 72 allows for continuation on next fine. 
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2 
Display line 2-5 contain fields for entering customer 

number, name, and address on left side; fields for 

entering ship-to name and address on the right. 
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Display line 7 contains headings. 
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Even-numbered display lines 8-20 contain fields for 
entering order data. 
Odd-numbered display lines 9-23 are defined as one- 












































inay vary slightly, 






character blank fields in order-to cause a blank line 
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to print on the 3284 and 3286 Model 1 and 2 printers. 
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Display line 22 contains visible head- 
ay ings and fields into which data can Ltt 
be placed. 
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Display tine 24 is initially nondis- pode de, | 
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play. At execution time, any one 
of the items can be changed to dis- 
play with normal or high intensity. 
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LEZURENCUSNU 2Y X Re 

FHEAD1] 0103 501v CUSTUMER NUMBER CUSTOMER NAME 
F SHIP Tu 

FCUSNO 0203 6 AN 

FNAME Uéél e2ly 


FSNAME U246 22 1GN 
FADORI] O321 22lku 
FSAUUR1U346 22 low 
FADUR2 u42l 2216 
FSAUDR2ZU446 22 low 
FADUR3 Ud2l 2216 
FSADUR3U546 22 LON 


* 

* THe FIELU NAMES SoOLANK-" wILL CAUSE A BLANK LINE TO PRINT NOT BE 
* SKIPPED UN THE 3284 AND 3280 MUOEL 1 AND 2 PRINTERS. 

* 


FULANKLU602 1Llv 


FHEAURLU703 816 QUANTITY 
FHEAUR2O712 Tle ITEM NG 
FHEAUR 30728 111G UcSCRIPTIUN 
FHEAUR40748 516 PRICE 
FHEADR50757 Lili wTY uN HAND 
FHEADR6OU770 LOLG BACK URDER 


FQTYL G803 U4 3Y 
FITEMNLUGI2 O08 LY 
FDESCR1U824 Z01LG 
FPRICE10848 7lo 
FUTYUHLUS6L 416 
FBAULKULUSTZ §=—41u 
FOLANK2U902 L1G 
FQTY2 1003 4 4Y 
FITEMNZ1lU12 @ LY 
FOESCR2Z1U24 2016 
FPRICE21U48) «~7lvL 
FQTYUH2Z1061 416 
FBACKU2Z1073 ~4lu 
FBLANK31102 ilo 
FQTY3 12403 4 4Y 
FITEMN31212 8 LY 
FDESCR31224 2OLlG 
FPRICE31248 7lv 
FUTYUH31Z61 416 
FBACKO3ic73 410 
FBLANK41302 lly 
FQTY4 140u3 4 3Y 
FITEMN41412 8 LY 
FOESCR41424 2016 
FPRICE41448 7Zlo 
FQTYGH41461 4lv 
FBACKO41473 416 
FBLANK51502° Llu 
FUTY5 1003 4 43Y 
FITEMNS161l2 6 1Y 
FDESCR51624 201 
FPRICE51045 Tilo 
FQTYGHSL66L 41u 
FBALKOSLoO73 416 
FBLANK61702°) Llo 
FUTY6 1003 4 3Y 
FITEMN61L612 8 LY 
FDESURG1424 2016 
FPRICE61848 Tie 
FQTYUR61861 416 
FBACKO61873 416 
FBLANK71902 116 
FQTY7 2003 4 3Y 
FITEMN72U12 8 LN 
FDESCR72024 2016 
FPRICE72U48 71G 
FQTYOH72U61 416 
FBACKO72073 416 
FBLANK82102) 116 


FIOTEX 2206 1016 EXCISE TAX 
FTAXEX 2218 416 

FTOTST 2225 916 STATE TAX 
FTAXST 2236 416 

FTOTLT 2243 916 LOCAL TAX 
FTAALT 2254 416 

FTOTAL 2262 516 TOTAL 


FTOTMONZ269 616 
FBLANKA2Z302 116 
FBLANK92402 11G 


FOUTOS 2404 1256 GUT UF STUCK 
FCUSERR2Z417 2056 GUSTUMER NOT ON FILE 
FITEMOR2439 1256 ITEM DROPPED 
FCREOOV2Z453 1156 CREDIT OVER 

“* 


| 


t 


SZOREN DISPLAY FORMAT INFORMATION 


EXECUTEON TIME DATA - SUFPUT AREA FORMAT — END POSITIONS FIR 








* FIELD FIELD END * FLELD FIELD END * 
* VAME LENGTH POSITIUN * NAME LENGTH POSITION * 
8 ween wee a werner ee ee eee * 
* oPcopeE 004 0004 =® LENGTH 004 0008 = * 
*  $ZOREN 006 oo20. 
LNPUT AREA FORMAT ~ END POSITIONS FOR RPG PROGRAMS 

* FIELD FIELD END * FIELD FIELD END * 
* YAME LENGTH POSITION * NAME LENGTH POSITION * 
Hwan eee ee Bane aoe ne ~ -- * 
* RTCODE 004 0004 * LENGTH 004 0008 
* - AID- 001 0015  *® CuUSNO 006 coz. * 
* SADDRL o2z2 0065 * SADDR2 022 0087 = ® 
* Qty. 004 OlL3) 0 ® TTEMNI 008 =, )SsO2s® 
*  LTEMN2 008 0133) *® «= «QTY3 004 0137 * 
* QTY4 004 01490 * ) ITEMNG 008 ols?) * 
*  LTEMNS 008 0169 * «QTY 004 0173. 
* QTY? 004 0185 * ITEMNT 008 0193. = 


LENGTH OF QUTPUT RECGRD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR9I2* ~- 0020 OTHER — 0012 


LENGTH OF INPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR9I2* - 0193 OTHER — 0185 


INFORMATION FOR USE DURING CCP ASSIGNMENT STAGE 


THE 
THE 
THE 


DECIMAL LENGTH OF THE FIELD DESCRIPTOR TABLE IS 1150 
DECIMAL LENGTH OF THE OUTPUT TEXT 1S 1146 
DECIMAL LENGTH OF THE INPUT TEXT IS 0240 


The generated display format appears as follows: 


Pe ee 


ora eEa TTEM NG beets tLe ts | PRICE PRM Ms im sweet) 


| 
i 
; 
1 
H 
| 
| 
i 
| 
1 
| 
i 
j 
| 
, 


be cod Ss Eg Rata! LOCAL TAX 





RPG PROGRAMS 


FIELO| 


FIELD 
NAME LENGTH 
YMNAME 006 
FIELD FLELO 
NAME LENGTH 
TMNAME 006 
SNAME 022 
SADOR3 O22 
Qty2 004 
ITEMN3 008 
QTys 004 
ITEMNG6 008 


END 
POSITI 


0014 


END 
POSITI 


0014 
0043 
0109 
0125 
0145 
Ol6k 
o18L 


ON 


ente 


ON 


ete eee nee 
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Example 2 — RPG II MRT Program Using the Display 
Format Facility 


This RPG || Multiple Requesting Terminal (MRT) program 
uses the Display Format Facility (DFF) to support the 3270 
terminals. Included in the example are a program descrip- 
tion, flowcharts, and RPG II coding. 


The terminal operator is requested to press the CLEAR key 
before entering the program name so that unwanted data is 
not received with the PROGRAM REQUEST. 


The application program will request the display format (by 
name) and cause it to be sent to the 3270 screen. The 
method of formatting the initial display for the order entry 
program is explained in Example 1 — DFF Formatting 
Example. The Order Entry display format was generated 
previously and stored in the object library with the name of 
$ZOREN. 


8-72 





When the initial format is placed on the screen, the cursor 
is positioned at line 2, position 3. 


CUSTOMER NUMBER © CUSTOMER NAME i Bi CAL 


CON ee a i 8) pee nets ited Ce MM Ss 


aes sTaTe TAX | LUCA, TAX 


The terminal operator enters the customer number and 
presses ENTER. 


CUSTOMER NUMBER CUSTOMER NAME H mai 
chs ye Hl 


i 
QUANITY FTEM NO Brea CA La soa PRM eae td 


EXCISE TAX PSEC i [melon Sd 





The program uses the number to retrieve the customer name, All data fields that have been modified are received by the 

customer address and ship-to information from the custo- application program. The items are verified by comparing 

mer master file. against the inventory master file. If items are verified and 
sufficient stock is on hand, the description and price are re- 
turned to the terminal. 


| If an item is not found, the item number field is changed to 
ee ee aie high intensity and ITEM DROPPED is displayed at high in- 


recte) CeCe eM Same Tat a . 
ome Co] ae tensity. 
eer a Se 
Cres a eC Sn eee 


ces PRR eet t) Pusat gts PRICE Pees ane od 


USES SS Re te) 

bey ad nD eu tet eat) NATIONAL SPORTING CO 
ae dy ae) 
och Bes ace sa 4 Bee 
Lite Et bb eit) AAs tS ee 


QUANITY ITEM NO bate TEAS Es | os he CMS Ses ae | 
aR) HOCKEY STICK LEFT ae) 


Et id 
37152081 BS 3 ME) 
STATE TAX ims meets 


ah md ead Rr s eae Cole 





EXCISE TAX Mater’ (ele Mg 


Pat a) 





Customer name and address fields are output fields and can- 
not be altered, but the ship-to fields are output/input fields 
and can be changed by the operator if necessary. Next, the 
quantity and item number for each item are keyed in and 
ENTER is pressed. 


If the item number is verified but there is insufficient stock 
on hand, the description, price, quantity on hand, and back 
ordered fields are displayed. OUT OF STOCK changes 
disrideouseoi- Gein ane ches from nondisplay to high intensity and the item is entered 


135624 Fat ae am en cr ates) in the back order file. 
+ 801 res 
oe eae 9 Pen Sie 


li aca a ae Once the item information is displayed, the operator can 
tan a Tt Car ear verify the status of the order and make any changes desired. 
aia For example, when OUT OF STOCK is indicated, the quan- 
rete tity field could be rekeyed for the intensified items. 


37152081 


bay 


| 
| 


EXCISE TAX aC sand ras med 
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For ITEM DROPPED, enter zeros in the quantity field to 
delete the entry. (Any item can be deleted by entering 


zeros in its quantity field.) 


After all exceptions have been satisfied, ENTER is pressed. 


When the program recognizes that all items have been 
processed and there are no exceptions, it calculates all 
prices and taxes and verifies customer credit status. 


iT 
SME sd CUSTOMER NAME 
LB Lye! NATIGNAL SPORTING CO 
sola ase 
cole a th ed 
ue See eee 


ere Re ame etm 
a SC 


Ae SL Ae Es 
HOCKEY STICK LEFT 


elk 
Raby. SS SSN ay RC) 


PSE Sere eae see 


pes TAX 41.38 STATE TAX 82.77 LOCAL TAX 82.77 
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sett 

NATIONAL SPORTING CO 
Ama 

To ee ae 
STEWARTVILLE, MINN 


a aoe SARA aa 
Pan 


TOTAL . 4345.20 





If the credit status is unacceptable, CREDIT OVER is dis- 
played at high intensity. The display now includes the 
total fields. , 


The operator verifies the order including totals and credit. 

If acceptable, the PF1 key (enter order key) is pressed, and, 
if the credit check was good, the inventory file and customer 
account file are updated and the display is printed on the 
3286. If the credit check was not good, the files are not up- 
dated but the display, iricluding the credit over field, is 
printed on the 3286. 


When the order has been completed and all files are updated, 
a new display format is sent to the terminal, ready for a 
new order. 


Any order may be canceled at any time by pressing the 
PA2 key (cancel order key). The program then displays 
a new display format on the terminal. 


The terminal may be released from the application program 
by pressing the PA1 key (release terminal key). The terminal 
would then be free to request another application and also 
may request the application program when desired by 
rekeying the program name. 


Operator requested to press CLEAR 
* key before entering program 

name. No data expected with 

program request. 


Set up 
Accept Input 
operation 


Accept Input 
operation 


Return code 
check 





Cancel order Release terminal 






Identify program 
request nore 


Any 
data entered 

and valid 
AID 












E2 


Yes No 





No 






PA2 
key pressed 


PAT 
key pressed 






Yes 


Clear total 
prices for this 
terminal 


Release this 


Set up to put 


initial format terminal 













Any 
invites outstand- 


ss 
H4 
Set up and execute 
Invite Input to End of job 
terminal last 


processed 


Output format Yes 


to terminal 





Note: Black numbers (Pe) correspond to similar 
numbers on the RPG II coding sheets. 





Order Entry Program Flow (Part 1 of 5) 
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Check if ship-to 


and name and ad- 
dress are not blank 


Order Entry Program Flow (Part 2 of 5) 
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Save terminal 
name 


Verified 
customer 
number 











Yes 





Find customer 
number in 
customer file 







Number valid 















Save customer 
name and address 
by terminal name 





Build Put Override 
record to display 
customer name and 
address, ship to 
name and address 


Put Override to 
display error data 









Operation 
successful 


Indicate error 
on display 





Initialize 
exception 
indicator 















Item number 
1 


{tem number 
given 


Item quantity 
given 





Find item number 
in inventory file 











Process item 
number 


Found in 
inventory file 


Indicate dropped 
item exception 







Set up to move 


price and descrip- 


tion to display 


Identify item 
number in format 
to intensify 








Order Entry Program Flow (Part 3 of 5) 
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27 


A2 













Indicate short 
quantity exception 





Quantity on 
hand less than 
ordered 










Identify number 
to move quantity- 
on hand and back 
order amount in 


ae Process item 
quantity 











in backorder 
file 


Indicate out of 
stock to be 
displayed 


Update inventory 
file, extend 
cost 






Increment to 
process next item 





F2 






Processed all 


items 


ES Yes 803) 


G2 





5F2 
No 


Y 


Order Entry Program Flow (Part 4 of 5) 
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Calculate taxes 


and totals 





B4 


B2 


Credit good 





Indicate credit 
check to be 
intensified in 
format 








Yes 


No PF1 
pressed 







No 
aes Credit good 


Totals 
previousty cal- 
culated 







Update customer 
account 


Save totals in 
terminal area 





F2 
Put Override to dis- 
play item descrip- 
tion, price, and if 
necessary, quantity 
on hand and back- 
order, and exception 
messages 






Copy display 
format to 
printer 












Operation 
processed 







H2 









Shut down 
request 





Operation 
successful 


Yes . (2) Yes 


= 






Order Entry Program Flow (Part 5 of 5) 
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RPG CONTROL CARD AND FILE DESCRIPTION SPECIFICATIONS 


IBM internationat Business Machine Corporation 





Program 
Programmer 


Filename 


Date 


8 
3 
5 
2 
= 
§ 
8 
“a 
= 
Qo 
2 
= 





[|S Inverted Print" 


File Type 
File Designation 
End of File 
Sequence 


Fite Format 


[ Punching 


| Instruction 


Control Card Specifications 


Model 20 


3 
8 


Number 
Of Print 


Positions Address 


to Start 


2152 Checking 
1P Forms Position 
File Translation 


Inquiry 


Overlap Printer 
® Binary Search 
& Tape Error 
8 Read/Write/Compute 
8 Keyboard Output 
3 Sign Handling 


Work Tapes 


3 Alternate Coilating Sequence 
Overlay Open 


23 2 


eo 
S 
eo 
Py 
Py 
ze 
o 
Ss 
jo 


File Description Specification 






Field Print 
i3_ Formatted Core Dump 


| _|& Table Load Halt 
[|_| Shared 1/0 

= 

& 


RPG to RPG II Conversion 


Graphic | | Card Electro Number. 
pce TT 








Made of Processing 
Length of Key Fiald or 
of Record Address Field 
Record Address Type 
Type of File 
Organization 
or Additional Area 


Key Field 
Starting 
Location 


Extension Code E/t 


UD/T or 2 























IBM International Business Machine Corporation 





Symbolic 
Device 








RPG EXTENSION AND LINE COUNTER SPECIFICATIONS 








Program 
Programmer 


Date 


1 
I 


Punching Graphic Card Electro Number 
Instruction Punch 


Extension Specifications 


Record Sequence of the Chaining File 























Labels S/N/E/M 


Refer to the specific System Reference Library manual for actual entries. 


2 53 64 Sh 56 57 58 59 60 61 62 63 64 65 G6 67 68 69 70 71 72 73 74 


GX21-9092 
Printed in U.S.A. 


75 76 77 78 79 80 


Program 
Identification 









File Addition/Unorderod 


Number of Tracks 
for Cylinder Overflow 


Number of Extents 


Extent Exit 
for DAM 


Name of 
Label Exit 


File 
Condition 






































Form X21-9091 
Printed in U.S.A. 


75 76 77 78 79 80 
Program 


off9 





ldentification 












































Number 
Number of the Chaining Field of Number g al Tabi g es 
Line To Filename Table or Entrles “ ; pent 5 2 ay nine ena 3 z Comments 
g Array Name i ; ona Entry la a 3 (Alternating Entry “18 
E From Filename oe ahAnay Se Format} Es 
5 ells Als 
3 4 5/67 Sf 10}%1 12 13 14 16 16 17 18419 20 21 22 23 24 25 26427 28 29 30 31 32]33 34 35/36 37 38 30/40 41 42]43)44]45 [46 47 48 49 50 51/52 53 54}55}/56457/58 59 GO 61 62 63°64 65 66 67 68 69.70 7172 73:74 
oft] |e [PL BELLIS | ret ety de 
of2] je PIA E AIRRIANY| ICIOWTIAT NIS| AlcicielP v P 
ofa] |e olple| lawl] [rinlrivry (elelmerla| bri |clowleiziie triciMel.| || | 1 | | 
ol4] TE i 6 6) z ; 
ols] Je NIM [tls] [wlolel] [AIRIElA| lolF| treRMizwlal. Ila tls| PROGR 
oye) JE CIOIMMIUINITCIA NG WITH). S| iBIUITIL EXECUTION 
o;7 E 
Lfolel le d JTPIRE | | | \é a ad 
E P S| [piu A KECUITIF/OIN| ITIP AINID INDIZICIAL 
E PIRITICle) HAs NU ICIAILICIUILATT € REN Colvls|z. 
E CIUIRIR RIDER} ELLE p TLELL 
E 
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RPG EXTENSION AND LINE COUNTER SPECIFICATIONS PmUGA 


Printed in U.S.A. 
IBM Internutional Business Machine Corporation 





75 76 77 78 79 80 


Program 
Identification lolRip| E INIT] 





Program Finching Graphic Card Electro Number 

















Programmer ] Date Instruction Punch 


Extension Specifications 


















































































E Fiecord Sequence of the Chaining File 
Number 
Number of the Chaining Field of Number ele e|_ 
' Table or Entries [| of Length | |= 8 Table: or Paneth 2/9 
Line To Filename ; of 3(<] Array Name | o¢ ale Comments 
& A N: Per Entries & i e 
Sy rray Name Entry Ja|=| 8] (Alternating | Entry a 
ec : Record | Per Table ry ila] ec axle! 2 
From Filename SE] S$] Format) 3] Ee] s 
E or Array S}5| 2 ala|é 
e lays ajold 
3.4 5)647 30 31 32/33 34 36136 37 38 30]40 41 42|43] 44/45/46 47 48 49 50 51/52 53 54]55]/56/57158 69 GO G1 62 63 64 65 66 G7 68 69 70 71 72 73 74 
1 E i 
ol2| le i 
ola] fe a (2 
ol4] Je 2 
ols] {E O 2 
ofe| |e i le 
ot7| |& " a 
o|s| le 7 
E | i 
E 7 
RPG EXTENSION AND LINE COUNTER SPECIFICATIONS Form x212009 
IBM International Business Machine Corporation 
" 75 76 77 78 79 80 
Program Punching Graphic Card Electro Number Program RID E NIT] 
Programmer Date Instruction | punch Identification 














Extension Specifications 









Number 
of 











Number 

























2] 2 

5|G| Table or ia sla 

i = igth gia 

To Filename oe ees ot Bl<] Array Name | of ale Comments 

rray Name & 2 

7 Per Table S| 8} (Alternating | entry {2 

els Format} els 

or Array, 3 3 $ a 

ala alg 


“Tippiice of liniem |) | 


PRI 
vn 


D 2 Ss 
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IBM International Business Machine Corporation 


RPG 


INPUT SPECIFICATIONS 








Program 
Programmer 


Line 


Farm Type 


78 





Punching 
Instruction 


Graphic 
Punch 





Record Identification Codes 














Filename 





Record Identifying Indicator 
+ 


A 
9 10 11 12 13/14 


Position 


c/2/D 


Field Location 





f IRECE VI 
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Lem 
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1 re 
fH Tee A eye ae ee eee ee ee ee ee ee 





ZL tL Ot 68 89 29 99 SO #9 £9 














19 09 69 








Decimal Positions 


Field Name 


i “| Card Electro Number ues 
row 5] ]ou9 





Control Level (L1-L9) 


Matching Fieids or 
Chaining Fields 








GX21-9094 
Printed in U.S.A. 


75 76 77 78 79 80 


Program E 
Identification 


Field 
Indicators 






























































Cee PERREEREr 


0/6. 4 





(Siege JT OSES WW Ne 


Sa 





=D =H -D=-Hp=H—-|D 
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ore, 
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a tt 
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2 Sv 
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zee 
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So 
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RPG INPUT SPECIFICATIONS pica USA, 


75 76 77 78 79 80 


1 
Card Electro Number 2 Program 
Page [ol | oF Identification O(RIDIE! N | 


IBM International Business Machine Corporation 


House, Punching Sinpnie L 
Programmer Date Instruction Punch 


R I ification Codes 
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Example 3—SRT Inquiry Program 


This example shows RPG II, COBOL, and FORTRAN IV 
coding for an inquiry program that uses the Display Format 
Facility to display information on the 3270. The three 
versions of the program use the same basic logic, inquire 


into the same three disk files, and use the samme screen 


format. The logic flow, display layout, display format 


specifications, and DFGR printout are shown on the 
following pages. 


This is a single requesting terminal (SRT) program; 


therefore, the program can handle only one inquiry on 
each execution. If sufficient main storage area is available, 
however, more than one copy of the program could be 


executing concurrently, serving different requestors. 


The terminal operator uses this inquiry program as 
follows: 


4, 


5. 


Signs on, keying /ONb [password], and presses the 
ENTER key. 


Presses the ERASE INPUT key. 


Enters a program request accompanied by input 
data, as follows: 

COBOL: 

COBINOWceccec/INHE 

RPG II: 

RPGINQ#ccccce/HIH 

FORTRAN IV: 

FORINQO#cccecc/IUIIIII 

where cccccc is a six-digit customer number and 
ITIL is an eight-digit item number. Presses the 
ENTER key. 


Program returns a message to the terminal operator. 


Program terminates. 


If the input from the terminal operator is incomplete or 
invalid, the program issues an appropriate error message. 


Notes: 


The three disk files used by the program are processed 
directly. 


In order to have the format remain on the screen after 


the program reaches end of job, ENDMSG-NO must be 
specified on the // PROGRAM assignment statement. 
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START 


.ccept input 


Error or Yes , 
exception 
return codg 





No 
D2 
Customer Yes | Move no customer 
number zero number entered to 








or blank 





} output message 








Read CUSTNAME 
and CUSTSHIP 
files 


ee ge a ee 


n 
= 


| Move invalid custo- 
mer number to out- 
put message 


Invalid custome 
umber 


No 


Move customer 
name and shipname 
to output message 


H2 


Yes | Move item number 
not entered to out- 
put message 


" S) 
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Read {TEM 
file 

















Move invalid item 
Aumber to output 
message 







Invalid item 
number 





Move item name 
and description 
to output message 


Put message 


End of job 
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C$ZRPTY 2V xX Re 


FHEAVRLU6O6 L2lv CUSTOMER NO. 
FCUSNO U62)b 62t 

FHEADR20606 1316 CUSTOMER NAME 
FCUSNM Us2l 222c 

FHEAUR31LU06 = 71G SHIP TO 
FSHPNM lu2l 222e€ 

FHEADR41306 816 ITEM NO. 
FITMNO 1321 62t 

FHEADR51506 1016 ITeM DESC. 
FITUSC 152i 202k 

* 


$ZRPIQ DISPLAY FORMAT INFURMATION 


EXECUTION TIME DAFA - OUTPUT AREA FORMAT - END POSITIONS =3R RPG PROGRAMS 


* FLEELD FIELD END * FIELD FIELD END * FIELD FLELD 
* VAME LENGTH POSITION * NAME LENGTH POSITION * NAME LENGTH 
Bn ee KO He meee wee ew= 0 were eo eeerwr— een 
* UPCODE 004 0004 * LENGTH 004 0008) * = TMNAME 006 
* sZRPLQ 006 0020 * CUSNO 006 0026 *® CUSNM 022 
* ~ SHPNM O22 0070 * ITMNO 008 0078 «=* ITDSC 020 
* 
” 
* 

LNPUT AREA FORMAT — END POSITIONS FOR RPG PROGRAMS 
* FIELD FIELD END * FIELD FIELD END * FIELD FIELD 
* AME LENGTH POSITION * NAME LENGTH POSITION * NAME LENGTH 
0 weeeee meee ee eee Bee eee eee ee Home te ee 
* RTCODE 004 0004 * LENGTH 004 0008 * TMNANE 006 
* = ALD- 001 0015 *® : 


LENGTH OF OUTPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR92* - 0098 OTHER - 0090 


LENGTH OF INPUT RECORD AREA REQUIRED IN DFF PROGRAM 
RPG *SUBR92* — 0025 OTHER - 0007 


INFORMATION FOR USE DURING CCP ASSIGNMENT STAGE 


THE DECIMAL LENGTH OF THE FIELD DESCREPTOR TABLE IS 9132 
THE DECIMAL LENGTH OF THE OUTPUT TEXT IS 0216 
THE DECIMAL LENGTH OF THE INPUT TEXT [S$ 0005 
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€ND 
POSITION 
0014 
0046 
0094 


END 
POSITION 


0014 


Rh EH 


ee ee 


SYSTEM/3 RPSIT 


O1dl H P 
RG 004 


o201 Fe 
0202 Fe SINGLE REQUESTOR INQUIRY PROGRAM WHICH USES THE 
0293 F* DISPLAY FORMAT FACILITY IN CCP. 


0204 FR 
0001 0205 FIERMIN IP 029 029 SPECTAL SUBR92 
0002 0206 F KPL 
0003 9207 FTERMOUT O 098 098 SPECIAL SUBR92 
0904 0208 F KPL 
0005 0209 FCUSTNAMEIC 300 3008 DISK 
0006 0210 FCUSTSHIPIC 256 128R O1SK 
0907 0211 FINVENTRYIC 300 300R DISK 
90098 9301 & PL 5 § 6 ComPILe TIME -——A compilation time array is used so that 
the array contains the accept input opera- 
tion code and the maximum input length 
9401 [eee KEY CUST. N06 6 / ETEM NOw 8 SUCH AS XXXXXX/YYYYYYYY when the TERMIN file is read. 
9009 0402 ITERMIN AA OL 
ONLO 9403 I 901 OO2ZORTNCOD 
OOLL 0404 1 015 0200CUSNO 30 eee 80 and 81 indicate when the 
9012 9405 I 921 021 SLASH ; 
0OL3 0406 I 922 02901TMNO 81 customer number or item number are 
0014 0407 ICISTNAMEAA 19 1 CM 2A zero or blank. 
9015 9408 1 009 030 CUSNM 
0916 0409 LCUSTSHIPBR LL 1 CM 2 CB 
onl? 9410 I 309 030 SHPNM 
OOLS O411L LTINVENTRYCC 12 1 CM 2 CI 
OOL? 9412 1 213 032 ITDSC 
002) 9501 ¢ SETON LR 
002k 0502 C N81 “ye COMP SLASH 05 
0022 9503 ¢ O05 SETON 858687 
9023 0504 CLRNOS 
0024 0905 CIR 91 
0025 0506 CNR 92 GOTO END 
0026 0507 CLRNILNBO = CUSND CHAINCUS TNAME 85 
0027 9508 CLAN9LN8O  CUSND CHAINCUSTSHIP 86 
0023 0509 CLRNOINBL ITMND CHAININVENTRY a7 
0029 9510 CLR END TAG 
9039 0511 CLR SE TNF 9192 
0031 0601 UTERMOUT T LR 
0032 0602 0 004 § CBt 
0033 0603 9 003 '98* 
0034 0604 U0 PLS ol4 
9608 O* 
1935 696 9 020 *$2RP19# 
OAn7 
9936 2608 3 CUSNO 026 
3609 J 
0937 9610 1 LONBONBSCUSNM 043 
9933 0611 ) W399 35 042 *NAME NOT ON FILE® 
0939 0612 ) 30 045 "NT CUST NO. ENTERED? 
2613 7% 
004) 0614 7 LLN8ON36SHPNM 070 
ON4L 9615 9 N89 84 064 "NAME NOT ON FILE® 
9942 9616 3 89 067 *NO CUST NO. ENTERED! 
JOLT 1 
0943 J618 ) LTMNO 073 
0619 1K 
004% 9620 } L2NALNSTITOSC 098 
0045 9621 1 N31 87 092 *ITEM NOT ON FILE# 
946 1622, 81 , 095 'ND ITEM NO. ENTERED! 
ee 
D 29 


Example 3 — RPG II Coding for SRT Inquiry Program 


3270 Display Format Facility (DFF) 8-99 


8-100 | 


STNO -AsesBoes COBOL SOURCE STATEMENT S osvccccescIDENTFON SEQ/NC S 
1 IDENTIFICATION DIVISION. 001010 
2 PROGRAM-ID. COBING. 001020 
3 REMARKS. THIS IS A SINGLE REQUESTOR INQUIRY PROGRAM THAT 001030 

USES THE DISPLAY FORMAT FACILETY OF CCP. 001040 

4 ENVIRONMENT DIVISION. 002010 
5 CONFIGURATION SECTION. 002020 
6 SOQURCE-COMPUTER. IBM-S3. 002030 
7 OBJECT-COMPUTER. 18H-S3. 002040 
8 INPUT-OUTPUT SECTION. 002050 
9 FILE-CONTROL. 002060 
10 SELECT CUSTNAME ASSIGN TO DA-5444~R-CUSTNAME 002070 
ACCESS IS RANDOM 002080 
ACTUAL KEY IS NAMEKEY. 002090 

11 SELECT CUSTSHIP ASSIGN TO DA-5444-R-CUSTSHIP 002100 
ACCESS IS RANOON 002110 

ACTUAL KEY IS SHIPKEY. 002120 

12 SELECT INVENTRY ASSIGN TO DA-5444-R-INVENTRY 002130 
ACCESS IS RANDOM 002140 

ACTUAL KEY IS INVTKEY. 002150 

13. DATA DIVISION. 003010 
14 FELE SECTION. 003020 
15 FD CUSTNAME 003030 
DATA RECORD IS CUST-NAME 003040 

LABEL RECORDS ARE STANDARD. 003050 

16 01 CUST-NAME. 003060 
17 05 FILLER PICTURE K(8). 003070 
18 O5 CUSNML PICTURE X(22). 003080 
19 05 FILLER PICTURE X(270). 003085 
20. FD CUSTSHIP 003090 
DATA RECORD IS CUST-SHIP 003100 

LABEL RECORDS ARE STANDARD. 003110 

21 01 CUST-SHIP. 003120 
22 05 FILLER PICTURE x(8). 003130 
23 O05 SHPNML PICTURE X(22). 003140 
24 O5 FILLER PICTURE X(98). 003145 
25 FD  INVENTRY 003150 
DATA RECORD IS INVEN 003160 

LABEL RECORDS ARE STANDARD. 003170 

26 Ol INVEN. 003180 
27 05 FILLER PICTURE X(13). 003190 
28 05 ITDSCL PICTURE X(20). 003200 
29 05 FILLER PICTURE X(276). 003205 
30 WORKING-STORAGE SECTION. 004010 
31 77 NAMEKEY PICTURE S$9{(7) VALUE ZERO. 004020 
32 77 SHIPKEY PICTURE S$9{7) VALUE ZERO. 004030 
33 77 INVTKEY PICTURE S$9(7) VALUE ZERO. 004040 
34 77 NO-CUSNO PIC X{(22) VALUE *NO CUST NUMBER ENTERED®. 004041 
35 77 NO-SHPNO PIC X(22) VALUE "NO SHIP NUMBER ENTERED’. 004042 
36 77 NO-ITMNO PIC X(22) VALUE ‘NO [TEM NUMBER ENTERED®. 004043 
37 77 INVALID-C PIC X(22) VALUE *INVALID CUST NUMBER = *. 004044 
38 77 INVALID-S PIC X(22) VALUE ‘INVALID SHIP NUMBER *. 004045 
39 77 INVALID~I PIC X(22) VALUE ‘INVALID ITEM NUMBER *. 004046 
ac eeeetonae ARILEELER AACE ee ee 004050 

* CCP-COBOL INTERFACE PARAMETER LIST. 004060 

ea Sueearuaneessa4ke<ccs ss css c4sesceds ec dduhesseenceecunsankanas 004070 

40 OL PARAMETER-LIST. 004080 
41 05 PL-RTC PICTURE S9(4) COMP-4, 004090 
42 05 PL-OPC PICTURE $9(4) COMP-4 VALUE 4. 004100 
43 05 PL-OUL PICTURE $914) COMP-4 VALUE 128. 004110 
44 05 PL-EFL REDEFINES PL-OUL PIC S914) COMP-4. 004120 
45 O5 PL-ATI REDEFINES PL-OUL PIC S9¢4) COMP-4. 004130 
46 05 PL-INL PICTURE S94) COMP—4 VALUE 16. 004140 
47 05 FILLER PICTURE X(8). 004150 
EEE ERE AA EEE EE EE EEK EEREEE SE AREE EE OKAE EKER EEE RE RE REEEARKE EK 004160 

* INPUT RECORD AREA. * 004170 
SRREERERE EERE RE RARE ARE RE ES EEE KEE EKER EERE REESE EE EERE EERE EER EE EE EE 004180 

48 O01 INPUT-A. 004190 
49 05 TERM-IN PICTURE X(6). 004200 
50 05 CUSNO PICTURE X(6) VALUE *000000". 004220 
51 05 ‘SLASH PECTURE X(L). 004230 
52 05 TTMNO PICTURE X(8) VALUE *"OO000000. 004240 
RARE ERE EE ARES EEE EE EKER EE EH REE ERE EER HERE ERERER ERE DKERERBEESE AE 004280 

* PUT FORMAT OUTPUT AREA. * 004260 
WR ERE EK E EEE EERE ER EH REE EE EE ER AE WERE EAE KE RE EAE EK EEEREEER ESE 004270 

53 01 OUTPUT-A. 004260 
54 05 TERH-QUT PICTURE X(6). 004290 
55 05 SCREEN PICTURE X(6) VALUE "SZRPIQ*. 004300 
56 05 CUSNO PICTURE X(6) VALUE ‘OO0000". 004310 
57 05 CUSNM PICTURE X(Z22) VALUE SPACES. 004320 
58 05 SHPNM PICTURE X(22) VALUE SPACES. 004330 
59 05 1TMNO PICTURE X(8} VALUE *00000000'. 004340 
60 05 TDSC PICTURE X(20) VALUE SPACES. 004350 
61 PROCEDURE DIVISION. 005010 
62 OPEN-THE-FILE. 005020 
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63 OPEN INPUT CUSTNAME. 
64 QPEN INPUT CUSTSHIP. 
65 OPEN INPUT INVENTRY. 
66 ACGEPT-INPUT. 
67 MOVE 4 TO PL-OPC. 
68 MOVE 15 TO PL~EFL. 
69 CALL *CCPCTOt USING PARAMETER-LIST+ INPUT—A. 
70 IF PL~-RTC NOT EQUAL TO O GO TO END~OF+J0B « 
72 GET-DISKDATA. 
73 MOVE CUSNO OF INPUT-A TO NAMEKEY. 
14 MOVE CUSNO OF INPUT-A TO SHTIPKEY. 
75 MOVE ITMNO OF INPUT—-A TO -INVTKEY. 
16 MOVE CUSNO OF INPUT-A TO CUSNO OF QUTPUT-A. 
77 MOVE ITMNO OF [NPUT—A TO I[TMNO OF OQUTPUT—A. > 
78 tf NAMEKEY IS EQUAL TO ZERO MOVE NO-CUSNG TO CUSNM 
80 ELSE PERFORM READ-C. 
82 TAGL. 
a3 LF SHIPKEY I$ EGUAL TO ZERO MOVE NC~SHPNO TO SMPNM 
85 ELSE PERFORM READ-S. 
87 TAG2. 
88 IF INVTKEY &S FQUAL TO ZERO MOVE NO-ITTMNQ TO I TDSC 
90 ELSE PERFORM READ-T. 
92 TAG3. 
93 GO TO CONTINUE-1. 
94 READ-C. 
95 READ CUSTNAME INVALID KEY GO TO ERROR-C., 
oT MOVE CUSNML TO CUSNM. 
98 GD TO TAGL.» 
99 READ~S. 
100 READ CUSTSHIP INVALIO KEY GO TO ERROR-S. 
102 MOVE SHPNML TO SHPNM. 
103 GO TO TAG2. 
104 READ-I. 
105 READ INVENTRY INVALID KEY GO TO ERROR-L. 
107 MOVE ITDSC1 TO ITDSC. 
108 GO TO TAG3. 
109 ERROR-C. 
110 MOVE INVALED-C TO CUSNM. 
iby GO TO TAGL. 
112 ERROR-S. 
113 MOVE INVALID-S TO SHPNM. 
114 GO TO TAG2. 
115 ERROR-I. 
116 MOVE INVALID-I TO I1TOSC. 
117 GO TO TAG3. 


116 CONTINUE~1. 
LL9 PUT-ROUTINE. 


120 MOVE 50 TO PL-OPC. 

121 MOVE 84 TO PL-OUL. 

122 MOVE TERMN~IN TO TERM-OUT. 

123 CALL *CCPCIO' USING PARAMETER-LIST, OUTPUT—A. 
124 END-OF-JOB. 

125 CLOSE CUSTNAME. 

126 CLOSE CUSTSHIP. 

127 CLOSE INVENTRY. 

128 STOP RUN. 
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005030 
005040 
005050 
005060 
005070 
005080 
005090 
005100 
005110 
005120 
005130 
005140 
905142 
005144 
005150 
005160 
005165 
005170 
005180 
005185 
005190 
005200 
005201 
005205 
005210 
005220 
005230 
005235 
005240 
005250 
005260 
005265 
005270 
005280 
005290 
005295 
005300 
005310 
005320. 
005330 
005340 
005350 
005360 
005370 
005380 
005390 
005400 
005410 
005420 
005430 
005440 
005500 
005510 
005520 
005530 
005540 
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ODAKRUP WN 


61 


10 
20 


30 
40 


50 
60 
70 
80 


90 


120 
130 


140 
1000 
10190 
1020 


PROGRAM FORINQ 

DEFINE FILE 8(1004300+LeIR8) .9(1004128yL 41 R9)210(100,309,L, TRIO) 
INTEGER * 2 PARM(8},RTC,OPCyOUTLy INL yICUST,ISHIP,ITEM 

INTEGER * 2 PUTBUF(92) -BUFFER (309), FNAME (6), INBUF(22) 

INTEGER * 2 MSG1022) »MSG2(22) »MSG3(22) eMSG4(22)4MSG5(22) 

INTEGER * 2 MSG6(22),SLASH 

EQUIVALENCE (RTC»PARM(1)),(CPC,PARM(2)) 

EQUIVALENCE (OUTL+PARM(3)),(INL,PARM(4)) 

DATA FNAME /'$ ZRPITQ S/S 


DATA MSGL JINO CUST NUMBER ENTERED SY 
DATA MSG2 JNO SHIP NUMBER ENTERED YS 
DATA MSG3 /§INO ITEM NUMBER ENTERED YY 
DATA MSG4 /tINVALTD CUST NUMBER "/ 
DATA MSGS /*I NV ALTO SHIP NUMBER "7 
DATA MSG6 SFI NVALTIOD ITTEM NUMBER "/ 
DATA SLASH /*/t/ 

OPC=4 _— 

QUTL=16 

INL=16 


CALL CCPFIC( PARM, INBUF) 

IF (RTC NE. 0} GO TO 140 
XCUST=GET CINBUF, 7,12,1.0) 
ICUST=XCUST 

ISHIP=ICUST 

CALL MOVECINBUF,1,6,PUTBUF,1) 
CALL MOVECFNAME »1,6,PUTBUF,7) 
CALL MOVE CINBUF,7,12,PUTBUF,13) 
CALL MOVE (CINBUF,14- 21, PUTBUF, 63) 
IF (ICUST) 10,110.20 

CALL MOVE (MSGl_ lk, 22,PUTBUF,19) 

GG TO 30 

READ (8*ITCUST,1LOOO,ERR=1L10) (BUFFER(T) »f=1,300) 
CALL MOVE( BUFFER ,9,30,PUTBUF 419) 
IF (ISHIP) 40+40,50 

CALL MOVE(MSG2¢1+22,PUTBUF +41) 

GO TO 60 

READ (9*TSHEP,1010,ERR=120) (BUFFER(T},1=1,128) 
CALL MOVE(BUFFER ,9,30,PUTBUF 141) 
IF (INBUF(13)-SLASH) 80,70,80 
XTEM=GETCINBUF »14,21,1.0) 
ITEM=XTEM 

IF CITEM) 80,80,90 

CALL MOVE(MSG341922+PUTBUF,71) 

GO TO 100 

READ (10° 1TEM,1020, ERR=130)(BUFFER(T ),I=1, 309) 
CALL MOVE (BUFFER, 14,33,PUTBUF,71) 
OPC=50 

QUTL=84 

CALL CCPFIO(PARM, PUTBUF) 

GO TO 140 

CALL MOVE(MSG4,1,22,PUTBUF,19) 

GO TO 30 

CALL MCVE(MSG5e1s22, PUTBUF,41) 

GO TO -60 

CALL MOVE (MSG6,_1, 22, PUTBUF,71) 

GO TO 100 

STOP 

FORMATC1LSOAL) 

FORMAT (128A1) 

FORMAT(103A1L) 

END 
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Example 4 — RPG II Order Entry Program (Using PRUF 
with the DFF) 


This illustrates the use of the PRUF capability with RPG II. 
The example is an order entry application program. 
Example 2 in this chapter illustrates an order entry 
application written as one large MRT program, and as 

can be seen, the logic becomes quite complicated. By 

using PRUF with DFF, the one program can be broken 

up into six smaller and logically much simpler programs. 
The six sample programs are described as follows: 


ORDERL-SRT Program Requested from the System Console 


ORDERL reads cards from the MFCU and formats the 
direct output HOLDORDR file (Figure 8-20), which will 
be used as a spool-type file to contain all orders entered 
from the 3270 terminals, with the master record for the 


file and all header records for the 3270 order entry terminals. 


The ORDERL program (Figure 8-21) requires input in the 
following format: 


Card 1, Columns 1 —A 
Columns 2-7, — Number of 64 character records 
, per allocation unit 


Cards 2-n, Columns 1.9 — H 
Columns 2-7 Symbolic terminal name of 
3270 order entry terminal 
Columns 8-9 — Number of allocation units to be 
assigned this terminal 


| 


The advantage of this order entry application is that the 
inventory file is not updated until the terminal’s PF1 key 
is pressed, which indicates that the order is complete. All 
orders are written to the HOLDORDR file, from which 
they can be printed via a stand-alone print program. They 
also can be printed at the time the orders are processed 
via a print program that runs as a CCP user task. 


The format of the HOLDORDR file is as follows: 








Order rec- 
ords for 
terminal n 






Order records | Order records 
for terminal 1| for terminal 2] ......... 


Master 
record 









For this example, n equals a maximum of six terminals. 


Prior to running the order entry program, the HOLDORDR 
file must be created in the following format: 



















Order record area 
for terminal 1 






Header record 
for terminal 1 


Master 
record 







Order record area 
for terminal 2 


Header record 
for terminal 2 






The master record is 64 characters long and is the first 
record of the HOLDORDR file. The format of the master 
record is as follows: 


Column/ Value Meaning 

Positions 

1 A Identifies the master record 

2-7 — RRECT A 6-digit number, repre- 
senting the number of 
records between header 
records 

8-13 TERMNAME,1 

14-19 TERMNAME,2 
Symbolic name of 
terminal 

38-43 TERMNAME,6 


The format of the 64 character header record is as follows: 


Column/ 

Positions Value Meaning 

1 H Identifies the header record 

2-7 RRECDN Relative record number of 
the next available record to 
start an order; initialized to 
relative record number of 
header record + 1 

8-13 RRECDP Relative record number of 
next order to print; initial- 
ized to the same value as 
RRECDN 

14-19 TERMNAME Symbolic name of terminal 


this space is allocated to 
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When the HOLDORDR file was created, space was allocated 
(RRECT) to contain a predetermined number of order 
records between header records. When a terminal has 

been found to have a high level of order entry, it is of 

great value to the user to create more than one header 
record for that terminal. This technique can multiply the 
space available for a particular terminal. 


When an order has been successfully entered, RRECDN 
will be updated to point to the record where the next 
order will start. When an order has been printed, 
RRECDP is updated to point to the next order to be 
printed. The printing of an order will allow another 
order to be entered in that record area (Figure 8-26). 


Prior to starting a new order, if RRECDP = RRECDN, both 
values are updated to point to the header record +1. This 
means that all the order record areas for that terminal 

are available. 


The HOLDORDR file is dynamic and needs to be formatted 
only initially. 


8-104 


The order entry application outputs an order in the 
following format: 


Record Number 
Relative to 
Start of Order 


Position Value Meaning 


1 1 N Identifies order 
heading 
2 1 
3-10 CRDNO Number assigned 
to order 
11-16 CUSNO Customer number 
17-38 CUSNAM Customer name 
39-60 CUSA1 Customer address 
field 1 
2 1 N Identifies order 
heading 
2 2 
3-24 CUSA2 Customer address 
field 2 
25-46 CUSA3 Customer address 
field 3 
3 1 N Identifies order 
heading 
2 3 
3-24 SHPNAM _ Ship-to name 
25-46 SHPA1 Ship-to address 
field 1 
4 1 N Identifies order 
heading 
2 4 
3-24 SHPA2 Ship-to address 
field 2 
25-46 SHPA3 Ship-to address 
field 3 
47-51 ZIPCD Zip code 
5 1 D First detail line 
of order 
2-3 LN Detail line 
number 
49 QTY Quantity 
10-17. ITMNO Item number 
18-37. ITMDSC Item description 
38-48 PRICE Price = Quantity” 
Price per item 
R 1 T Total line 


2-12 Cost excl. Tax 
13-22 State tax 

23-32 Federal tax 
33-43 Total cost 


A detail record is written for every ITMNO entered by the 
order entry operator. 


The order entry application functions as follows: 


The order entry operator requests the order entry appli- 
cation by keying in ORDER1BCUSNG/ORDNO where 
CUSNO is a 6-position customer number and ORDNO is 
an 8-position order number field. ORDER1 (Figure 8-22) 
reads the CUSTNAME and CUSTSHIP files, and if found 
performs a PRUF-Put message to the 3270 terminal of the 
data retrieved. The cursor is left positioned under the 
ship-to information. The operator can override this infor- 
mation if so desired. The first field of the screen is a type 
7 output/input field which has the value of ORDER2b. 
After the ship-to information has been updated, the 
operator presses the ENTER key. This is actually a pro- 
gram request for ORDER2 (Figure 8-23). ORDER2 inputs 
the fields using $ZORD1 as the controlling format for 
inputting the program request data. ORDER2 writes the 
four N records to the HOLDORDR file and performs a 
PRUF-Put message operation to format the 3270 with 
header information for entering QTY and ITMNO. The 
first field on the screen is a type 7 output/input field of 
value ORDER3#. The cursor is positioned to allow input 
of the OTY field. The operator keys in the QTY number 
-and ITMNO number and presses the ENTER key. This is 
a program request for ORDERS (Figure 8-24). ORDER3 
inputs the QTY and ITMNO numbers using $ZORD2 as 
the controlling format for the program request data. If 
the ITMNO number is found, the following information 
is displayed under the QTY and ITMNO headings: 


LINE NO. QTY  ITMNO ITM DES PRICE 
02 


01 XXKXXXK XXXXKXKXKXK wea ecene XXXX.XX 


The cursor is positioned under the QTY field, however if 
line number 01 is found to be in error, the operator can 
backspace to the line number field and enter 01 followed 
by the correct OTY and ITMNO. ORDER3 will write 

out a D (detail) record in the HOLDORDR file if the line 
number field is not equal to the previous line number 
record. In this example, line number 01's D record is 
written following the successful entry of line number 02, 
or the PF key is pressed to indicate the order is complete. 


When the PF1 key is pressed, ORDER@ issues a PRUF- 

Put message to the operator indicating to press the ENTER 
key which completes the order. Now a program request 
for ORDERG is issued (Figure 8-25). ORDER4 inputs 

all D records written for this order, updates the inventory 
file, writes the T (total) record for the order to the 
HOLDORDR file, and updates the RRECDN value in the 
header record for that terminal. The terminal is now in 
command mode, and is available for the next order entry 
request or other program requests. 


It should be noted that after issuing a PRUF-Put message, 
ORDER1 and ORDER2 go to end of job; that is, as the 
Operator keys in data on the terminal, the terminal buffer 
is being used, not the user’s program area in main storage. 
When the ENTER key is pressed, the next program is 
requested and all non-output fields with MDT-ON are 
passed under format control to the requested program. 
Figure 8-28 shows the assignment set requirements for the 
order entry application, and Figure 8-27 shows orders after 
they have been printed by ORDERP. 


The formats used in this sample order entry program are 
illustrated in Figure 8-29. The following chart lists the 
programs and the formats they use: 


Program Formats 
ORDER1 $ZORD1 
$ZORD5 
ORDER2 $ZORD2 
$ZORD5 
ORDER3 $ZORD3 
$ZORD4 
$ZORD5 
ORDER4 $ZORD5 
$ZORD6 
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*A001L000N32112N32112N32142N32102N* 


*32002N32002 * 
*H000018000003N32 112 * 
* * 
*NL00000006000006BROWN WHOLESALE * 
* SUPPLY SEVILLE * 
#N2PHILA., PENN * 
7 * 
*N3SLAY BROS INC WELLS* 
* 2 
*N4PHILA.+ PENN TRUCK * 
* 00000 * 
*D0100000100000001 BLUE FLUORES* 
*CE 000000000013000 
*D0200000200000001 BLUE FLUORES 
*CE 000000000026000 
*T0000003900000000015600000001950* 
*00000042510 * 
+N100000020000010BLACK&JONES CHEM* 
*ICAL C 19TH STREET * 
*N2PHILADELPHIA; PENNA. * 
* a 
*N3SAME * 
* * 
*N4 TRUCK *® 
* 00000 * 
*D0100000200000002 X02 PLUG * 
* 000000000003426 * 
*D0200000300000003 X03 PLUG * 
* 000000000003600 * 
*D0300000400000004 X04 PLUG * 
* 000000000006800 * 
*T0000001382600000005530000000691+ 
00000015070 

* : 
*H002018002003N32142 * 
* * 
*NL00000005000005FAST ELECTRONICS* 
* W GLENWOOD * 
*N2PITTSBURG, PENN * 
* * 
*N3SAME * 
* * 
*NG AIR FREI* 
*GHT 00000 * 
*D01000001400000002 X02 PLUG * 
* 000000000001713 * 
*D0200000400000001 | BLUE FLUORES* 
*CE 000000000013000 


*D0300000400000001 BLUE FLUORES* 
*CE = 000000000052000 * 
*T0000006671300000026680000003335* 
*00000072716 * 


*NL00000009000009 JOSEPH CLARKE * 
* 1520 MAPLE STREET * 
*N2MAPLEWOOD, OHIO * 
* * 
*N3 SAM BLIZZARD SAME * 
* k 
*N4 SAME FIRST C* 
*LASS MAIL 00000 * 
*D0100000400000004 X04 PLUG * 
* 000000000010500 * 


Figure 8-20. HOLDORDR File Organization 


*T0000001730000000006920000000865* 


*00000018857 * 
* * 
*HO03018003003N32102 * 
aK K 
*xNLOOCOOOO7OOOO07BENNETT INC * 
* CHESTNUT * 
*N2PHILA., PENN * 
* * 
*N3SAME * 
oe * 
*NG AIR FREI* 
*GHT 00000 * 
*D01L00000100000001 BLUE Epona 
*CE 000000000013000 

*D0200000200000002 X02 PLUG : 
* 000000000003426 * 


*D0300000300000003 X03 PLUG * 
* 000000000003600 * 
STOOOOUG 200 2e0000nOTeOLeOD ECOL ORE 
*00000021828 

*N100000008000008 STEPHANIE BOOKS 
* MAPLE STREET 

*N2 GREENVILLE, NEW YORK : 
* * 


*N3 JOHN BOOKS CLEMENTS* 
*ON COLLEGE * 
*N4 GETTYSBURG, PENNA. PONY ani 
*PRESS 00000 
*D0100000100000001 BLUE FLUORES 
*CE 000000000013000 
*D0200000400000004 X04 PLUG 
* 000000000006800 * 


*T0000001980000000007920000000990%* 
*00000021582 * 
* * 


*H004017004003N32002 

* 

*N100000003000003D & ¢ SHIPPERS 
FILBERT 

*N2 PHILA.» PENN 

* 


HR HeHHRHK 


*N3SAME 
* 


*N4 AIR FREI 
*GHT 000c0 
*D0100000500000005 X05 PLUG 

* 000000000010500 
*D0200000600000006 X26 PLUG 

* 000000000010800 


HNHHeKKHHK SE 


+ TOON DOO e IS DOROORND Baron ROOD tO FET 
*00000023217 
*NLOOOOOO03Z000002CARLSON BYRNES cs 


#0 N BROAD 

*N2PHILAs, PENN * 
* #e 
*N3W K GARRISON CO SANS* 
*OM * 
*N4PHILA.» PENN TRUCK * 
* 00000 * 
*D0100000200000003 X03 PLUG = * 
* 000000000002400 * 
*D0200000100000002 X02 PLUG * 
* 000000000001713 * 
*T0000000411300000001640000000205% 


*00000004482 


* * 


0101 H R 4 


Figure 8-21. ORDERL Program 


CROERL 


0201 FCARDIN IPE 96 96 MFCUL ORDERL 
0202 FHOLOGROSOC 64 64R DISK45 CRDERL 
0203 FPRINTOUTO 132 132 PRINTER ORDERL 
0301 E€ TERM 6 6 ORDERL 
0401 ICARDIN AA 10 1 CA ORDERL 
0402 I 2 TORRECT 40 ORDERL 
0403 I AB 20 1 CH ORDERL 
0404 I OR 30 LNCA INCH ORODERL 
0405 I 2 7 TRMNM ORDERL 
0406 I 8 9ON a5 ORDERL 
0407 I 1 96 CARD OQRDERL 
0501 C 30 IF INVALID CAROGRDERL 
0502 CORN80N10 OR RRECT ZERO CRDERL 
0503 CORN80 10 40 SETON LR50 SET ON LR AND ORDERL 
0504 C LR GOTO END PRINT ERROR MSGORDERL 
0505 € 10 Z-ADDO I 10 CHECK FOR ORDERORDERL 
0506 C 10 SETON 80 OF INPUT CAROS ORDERL 
0507 C 10 Z-ADD2 RRECDH 60 SET REC NUM=TWOORDERL 
0508 C 10 GOTO END READ NEXT CARO GROERL 
0509 C MOVE RRECDH RREC1 60 OROERL 
0510 € RRECOH ADD lL RRECDD 60 HDR REC PLUS 1 ORDERL 
0511 C Looe TAG CRDOERL 
0512 C I AOD 1 I QROERL 
0513 C 7 comp I TOMAX OF 6 TERMS ORDERL 
0514 C 70 SETON 50LR ORDERL 
(9515 C 50 GOTO END OROERL 
0516 C MOVE TRMNM TERM, CRDERL 
0517 C RRECOH ADD RRECT RRECDH BUMP TQ NXT HDRORDERL 
0518 C N85 N suB 1 N 8585 GRDERL 
0519 C N85 GOTO LOOP ORDERL 
0520 C RREC1 CHAINHOLDORDS 60 GET HEADER REC ORDERL 
0521 C 60 SETON LR50 FOR THIS TERM GRDERL 
o522 C END TAG ORDERL 
0523 C SETOF 85 ORDERL 
0524 CLRN50 1 CHAINHOLDORDS GET MASTER REC ORDERL 
0601 GPRINTGUTH 201 iP GROERL 
0602 0 13 "RECORD NUMBER' ORDERL 
0603 0 30 "TERMINAL NAME® CRDERL 
0604 O Dol 20 ORDERL 
0605 O RRECL 10 ORDERL 
0606 0 TERM,I 25 ORDERL 
0607 O T 3 LR 50 CROERL 
0608 O CARD 96 . CRDERL 
0609 0 10 40 125 *RECORDS/TERMINAL INVALID® ORDERL 
0610 0 30 126 "INVALID CARO TYPE? CRDOERL 
0611 0 60 126 ‘ENO OF ORDER FILE? GROERL 
0612 0 70 126 *MORE THAN 9 TERMINALS? ORDERL 
0613 OHOLDORDSD 20 ORDERL 
0614 0 1 ‘Ht CRDERL 
0615 0 RRECOD 7 CROERL 
0616 O RRECDD 13 QRDERL 
0617 O TERMI 19 ORDERL 
0618 O T LRN5O CROERL 
0619 O 1 "At ORDERL 
0620 0 RRECT 7 CRDERL 
0621 0 TERMs1 13 GROERL 
0622 0 TERM,2 19 OROERL 
0623 0 TERM, 3 25 CROERL 
0624 0 TERM +4 31 ORDERL 
0625 O TERM,5 37 ORDERL 
0626 O TERM,6 43 ORDERL 
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0101 H R 4 OROERL 


0201 FTERMIN IP 29 29 SPECIAL SUBR92 CROERI 
0202 F KPL CROERL 
0203 FTERMOUT O 215 215 SPECIAL SUBR92 ORDER1L 
0204 F KPL QRDER1L 
0205 FCUSTNAMEIC 300 300R DISK CRDER1 
0206 FCUSTSHI PIC 256 128R DISK OROER1 
0300 E* THE FOLLOWING COMPILE TIME ARRAY HAS ACCEPT INPUT LENGTH OF 29 QROERI 
9301 E PL 5 5 6 CRDERL 
0400 [* THE FOLLOWING INPUT IS DATA WITH PROGRAM REQUEST ORDER 
0401 ITERMIN AA 01 ORDERL 
9402 I 1 20RTNCOD ORDERL 
0403 I 15 200CUSNO 80 CRDERL 
0404 I 21 21 SLASH CRDER1 
0405 I 22 2900RDERN 81 ORDERL 
0406 ICUSTNAMEAA 10 1 CM 2 CA CRDERL 
0407 I 9 30 CUSNM GROER1 
0408 I 34 55 CUSAL ORDER1 
0409 I 59 80 CUSA2 CRDERL 
0410 I 84 105 CUSA3 ORDER1 
0411 ICUSTSHIPAA 11 1 CM 2 CB QRDER1 
0412 I 9 30 SHPNM ORDERL 
0413 I 34 55 SHIP1 ORDER1 
0414 I 59 80 SHIP2 CROERI 
0415 I 84 105 SHIP3 ORDER] | 
0416 I 109 1130ZIPCD CROERL 
0501 C SETON LR20 ORDERL 
0502 C 91 CROER1L 
0503 COR 92 SETON 30 CRDERL 
0504 C 30 ORDERL 
0505 COR 80 GRDER1 
0506 COR 81 GOTO END CROER1 
0507 C nye COMP SLASH 8181 VALID SEPARATORORDERL 
0508 C 81 GOTO END CRDER1L 
0509 C CUSNO CHAINCUSTNAME 85 VALID NAME ORDER1 
0510 C N85 10 CUSNO CHAINCUSTSHIP 86 VALID ORDER NUMORDERL 
0511 C 85 FOUND INPUT ERRORDERL 
0512 COR 86 DO PUT OVERRIDECROERL 
0513 CORNIO ORDERL 
0514 CORN11 GOTO END QRDERL 
0515 C SETOF 20 NO PUT OVERRIDECRDERL 
0516 C END TAG ORDER1I 
0600 O* IF PUT OVERRIDE OCCURS MUST MAKE ANOTHER PROGRAM REQUEST ORDERL 
O517 C SETOF 9192 ORDER1 
0601 OTERMOUT D LR 20 ORDERL 
0602 0 4 * CB QRDER1 
0603 0 8 "42! ORDERL 
0604 0 PL»5 14 ORDERI 
0605 O 20 '$Z0RD5* CRDER1 
0606 O Nil 40 "INVALID CUSSHIP FILE® CRDERL 
0607 0 N10 40 "INVALID CUSTMAS FILE* CRDERL 
0608 O 86 40 "NO CUSSHIP RECORD : CROERL 
0609 0 85 40 "NO CUSTMAS RECORD ‘ ORDERL 
0610 0 81 40 ‘INVALID ORDER NUMBER‘ CRDER1L 
0611 0 80 40 "ENVALIO CUST. NUMBER* ORDERI 
0612 0 30 40 "ERROR RETURN CODE = * CRDERI 
0613 0 30 RTNCOD 42 ORDER 
0614 0 T LRN2O ORDER1 
0615 0 4 * GBI CRDER1 
0616 O 8 '215° ORDERL 
0617 O PL 5 14 CRDER1 
0618 0 20 '$ZORO1! ORDER1 
0619 0 ORDERN 28 CRDER1 
9620 0 CUSNO 34 OROERI 
0621 0 CUSNM 56 ORDER1 
0622 0 SHPNM 78 CRDERL 
0623 0 CUSAL 100 ORDER 
0624 0 SHIP1 122 GRDER1 
0625 0 CUSA2 144 ORDERL 
0626 O SHIP2 166 ORDERL 
0627 0 CUSA3 188 GROER1 
0628 O SHIP3 210 OROERI 
0629 O ZIPCD 215 ORDER 
Ee 


0 29 


Figure 8-22. ORDER1 Program 
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0101 
0201 
0202 
0203 
0204 
0205 
0301 
0302 
0401 
0402 
0403 
0404 
0405 
0406 
0407 
0408 
0409 
0410 
0411 
0412 
0413 
0414 
0415 
0416 
0417 
'0418 
0419 
0420 
0421 
0422 
0423 
0424 
0425 
0426 
0427 
0428 
0501 
0502 
0503 
0504 
0505 
0506 
0507 
0508 
0509 
0510 
0511 
0512 
0513 
0514 
0515 
0516 
0517 
0518 
0519 
0520 
0521 
0522 
0523 
0524 
0525 
0526 
9527 
0528 
0529 
0530 
0531 
0532 
0533 
0534 


* 0535 


0536 
0537 
0538 
0539 
0540 


H oR: 4 
FTERMIN IP 
F 

FTERMOUT © 
F 

FHOLDOR D5UC 
E 

E 

ITERMIN AA 
I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 
IHOLDORDSAA 
I 

I 

I 

I 

I 

I 

I 

I AB 
I oR 
I 

I 

I 

c 

c 92 

COR 92 

c 

c 

c 50 

COR 60 
CORN3O 

c 

c 

C 

Cc NTO 

C 56 

c 

c 

Cc N71 

Cc N71 

c 

c 

c 50 

COR 55 

COR 60 
CORN4O 

c 

C 65 

Cc 65 

Cc 65 

C 

c 

c 

c 60 

c 

c 

c 60 

C 

c 

c 60 

c 

c 

c 60 


217 217 
280 280 
64 64 
p 
T 
01 
30 1 CA 
40 1 CH 
80 INCH 
1 
PLS 
TAGL 
I 
RREC# 
RREC# 
RRECOD 
RRECDH 


SPECIAL 
SPECIAL 
R OISK45 
L 5 5 6 
ERM 6 6 
1 
15 
16 
23 
31 
37 
59 
81 
103 
125 
147 
169 
191 
213 
2 
8 
14 
20 
26 
32 
38 
LNCA 
2 
8 
14 
SETON 
GOTO END 
SETOF 
CHAINHOLDORDS5 
GOTO END 
Z-ADD2 RREC# 
MOVE 1 I 
LOKUPTERMy I 
SETON 
GOTO END 
TAG 
SUB 1 I 
ADD RRECT RRECH 
GOTO TAG1 
MOVE RREC# RRECDH 
CHAINHOLDGRDS 
GOTO END 
COMP RRECOP 
ADD 1 RRECOD 
MOVE RRECDD RRECDP 
EXCPT 
SETOF 
MOVE RRECOD RREC# 
EXSR READF 
GOTO END 
SETON 
EXSR CHECK 
GOTO END 
SETON 
EXSR CHECK 
GOTO END 
SETON 
EXSR CHECK 
GOTO END 


Figure 8-23 (Part 1 of 2). ORDER2 Program 


SUBR92 OROER2 

KPL : ORDER2 
SUBR92 ORDER2 

KPL CROER2 
ORDER2 

ORDER2 

ORDER2 

ORDER2 

20RTNCOD ORDER2 
15 AID ORDER2 
22 PGMNAM GRDER2 
300 ORDNUM ORDER2 
360CUSNO GRDER2 
58 “CUSNM GRDER2 
80 SHPNM ORDER2 
102 CUSA1 ORDER2 
124 SHPA1 ORDERZ 
146 CUSA2 CROER2 
168 SHPA2 ORDER2 
190 CUSA3 ORDER2 
212 SHPA3 CRDER2 
2170Z1PCD ORDER2 
ORDER2 

TORRECT 50 ORDER2 
13 TERMy1 ORDER2 
19 TERM,2 ORDER2 
25 TERM,3 ORDER2 
31 TERMy4 ORDER2 
37 TERM, 5 ORDER2 
43 TERM, 6 ORDER2 
GROER2 

ORDER2 

7ORRECDD 50  ORDER2 
130RRECOP 55  ORDER2 
19 TRMNM ORDER2 
1020LR ORDER2 
NONE ZERO RETURPRDER2 

CODE PUT ERRMSGORDER2 

20 CRDER2 

60 GET MASTER REC ORDER2 

BAD ORDER FILE CRDER2Z 

ORDER2 

CRDER2 

60 ORDER2 
10 CROER2 
TOFIND THIS TERM GRDER2 

56 INVALID TERM  ORDER2 
ORDER2 

CRDER2 

71 ORDER2 

BUMP REC NUM TCCRDER2 

POINT TO HEADERCRDER2 

60 REC FOR THIS ORDER2 
60 TERMINAL ORDER2 
OROER2 

CROER2 

ORDER2- 

ORDER2 

651F ALL ORDERS ORDERZ 

FOR THIS TERM ORDER2 

PRINTED, RESET CRDER2 

TO FIRST RECOROORDER2 

65 ORDER2 
ORDER2Z 

ORDER2 

CRDER2 

51 FIRST "N* REC ORDER2 
ORDER2 

ORDER2 

52 SECOND 'N* REC ORDER2 
CROER2 

ORDER2 

53. THIRD 'N* REC CRDER2 
ORDER2 

ORDER2 


ORDER2 
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0541 C SETON 54 FOURTH "N* REC ORDER2 
9542 C EXSR CHECK ORDER2 
0543 C 60 GOTO END ORDER2 
0544 C SETOF 1020 ORDER2 
0545 C END TAG ORDER2 
0546 C SETOF 9192 ORDER2 
0547 CSR RE ADF BEGSR : ORDER2 
0548 CSR SETOF 304080 ORDER2 
0549 CSR RREC# CHA INHOLDORD5 60 GET NEXT RECORDORDER2 
0550 CSR 60 SETON 40 ORDER2 
0551 CSR ENDSR ORDER2 
0552 CSR CHECK BEGSR CRDER2 
0553 CSR .  EXCPT WRITE REC TO ORDER2 
0554 CSR RREC# ADD 1 RREC# HOLDOROS FILE ORDER2 
0555 CSR EXSR READF ORDER2 
0556 CSR ENDSR ORDER2 
0601 OHOLDOROSE 51 ORDER2 
0602 OD lL 'Nt ORDER2 
0603 0 N52N53N54 a ub GRDER2 
0604 0 N52N53N54QRDNUM 10 ORODER2 
0605 0 N52N53N5 4CUSNO 16 ORDER2 
0606 O N52N53N54CUSNM 38 ORDER2 
0607 O N52N53N54CUSAL 60 CRDER2 
0608 O 52N53N54 : 2 #28 CRDER2 
0609 0 52N53N54CUSA2 24 ORDER2 
0610 O 52N53N54CUSA3 46 ORDER2 
0611 0 53N54 2003" ORDER2 
0612 0 53N54 SHPNM 24 ORDER2 
0613 0 53N54 SHP Al 46 ORDER2 
0614 0 54 2 "4s ORDER2 
0615 0 54 SHPA2 24 ORDER2 
0616 0 54 SHPA3 46 OROER2 
0617 O 54 ZIPCD 51 ORDER2 
0618 O E 65 CRDER2 
0619 O RRECOD 7 ORDER2 
0620 0 RRECDP 13 CRDER2 
0621 OTERHOUT OD 10 ORDER2 
0622 0 4" cet ORDER2 
0623 0 8 "42! ORDER2 
0624 0 PL+5 14 CRDER2 
0625 0 20 '$ZORD5* ORDER2 
0626 Q 20 40 "ERROR RETURN CODE = * CROER2 
0627 0 N20N60 40 "INVALID ORDER FILE §¢ ORDER2 
0628 O N20 56 40 "TERMINAL NOT IN FILE® ORDER2 
0629 0 N20 60 40 "END OF ORDER FILE : CROER2 
0630 O 20 RTNCOO 42 ORDER2 
0631 0 D N10 LR ORDER2 
0632 0 4 * GBt ORDER2 
0633 0 8 *2a0' ORDER2 
0634 0 PL»5 14 CGROER2 
0635 0 20 *$Z0R02° ORDER2 
0636 O RRECDH 26 CRDER2 
0637 O RREC# 32 OROER2 
0638 0 OQRDNUM 40 ORDER2 
0639 0 CUSNO 46 CRDER2 
0640 0 CUSNM 68 ORDER2 
0641 0 SHPNM 90 QRDER2 
0642 0 CUSAL 112 QRDER2 
0643 0 SHPAL 134 ORDER2 
0644 0 CUSA2 156 ORDER2 
0645 0 SHPA2 178 ORDER2 
0646 0 CUSA3 200 CRDER2 
0647 O SHP A3 222 ORDER2 
0648 O ZIPCco 227 QRDER2 


ae 
D 217 


Figure 8-23 (Part 2 of 2). ORDER2 Program 
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0101 
0201 
0202 
0203 
0204 
0205 
0206 
0301 
0302 
0303 
0401 
0402 
0403 
0404 
0405 
0406 
0407 
0408 
0409 
0410 
0411 
0412 
0413 
0414 
0415 
0416 
0417 
9418 
0419 
0420 
0421 
0422 
0423 
0424 
0501 
0502 
0503 
0504 
0505 
0506 
0507 
0508 
0509 
0510 
0511 
0512 
0513 
0514 
0515 
0516 
0517 
0518 
0519 
0520 
9521 
0522 
0523 
0524 
0525 
0526 
0527 
0528 
0529 
0530 
9531 
0532 
0533 
0534 


HR 4 
FTERMIN IP 
F 

FTERMOUT 0 
F 

FHOL DOR O5UC 
FINVENTRYIC 
E 

E 

£ 

ITERMIN AA 
I BB 
I oR 
I OR 
I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 

I 
IHOLDOROSAA 
I oR 
I 
LINVENTRYAA 
I 

I 

I 

c 

c 

c 

c 

c 

C NBL 

C 

c 691 

COR 92 

G 

c 10 

c 
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Figure 8-27 (Part 2 of 3). Sample Output of ORDERP Program 
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SHIP TO 


SAME 


AIR FREIGHT 


CESCRIPT TON 


RLUF FLUCRESCF 
XO? PLUG 
XxO% PLUG 


TOTAL 

STATE TAX 
FENERAL TAX 
TOTAL ORNER CNST 


99900008 AATF 2/16/75 


SHIP TO 


JOHN BOOKS 
CLEMENTSON COLLEGE 
CETTYSBURG, PENNA. 
VIA BEST WAY 


FESCRIPT ION 


PLUE FLUE RES CE 
KO4 PLUG 


TOTAL 

STATF TAX 
FEDERAL TAX 
TOTAL ORDER COST 


cocac 
enst 


6e@.Cc 
105.0C€ 


6.65 
18E.57 


cococ 
cost 


13c¢.ce 
68.00 


1Se.cc 
1292 
€2SC 
215.82 


CRDER KUPRER 00000003 CATE 2/16/75 


CUSTOMER SHIP 10 
D & C SHIPPERS SAME 
FILRFRT 
PEIL As, PENN 
AIR FREIGET eccece 
QUANT TTY ITFM RFSCRIPT ION cnSstT 
ann0cs cccecces XO5 PLUG 10§.CC 
onnace CCOCCCLS X26 PLUC 1ce.cc 
TOTAL 213.¢C 
STATE TAX 8.52 
FEDERAL TAX 10.65 
TOTAL ORDER COST 232.17 
CROFR NUMAER 00000003 NATE 2/16/75 
CUSTOMER SHIP TO 
CARLSON BYRNES Cn Ww « GARRISON CO 
N BROAD SANSOM 
PEIL As, PENN PEILAs, PENN 
| TRUCK ccccc 
QUANT ITY , ITEM RESCRIPT ION cnst 
concc? ccecocecs X03 PLUG 24.CC 
nnocol cccocco2 X02 PLUG 17.13 
TOTAL 41.13 
STATE TAX 1.64 
FEDERAL TAX 2205 
TOTAL NRNMER COST An B2 


Figure 8-27 (Part 3 of 3). Sample Output of ORDERP: Program 
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4/ 
‘tf 
tf 
tt 
4/ 
4f 
47 
4/ 
tf 
tf 
v} 
4/ 
tf 
tf 
4 
4? 
4t 
4t 
4é 
Vi 
4 
4a 
4/ 


DISKFILE NAME-KOL DORD5,ORG~D REC L-64 
DISKFILE NAME-CUSTSHIP »ARG—-D,RECL-128 
OISKFILE NAME-CUSTNAME ,ORG-D »RECL-3C0 
DISKFILE NAME-INVENTRY »ORG—D »RECL- 300 
PROGRAM NAME-ORDERL » ENDMSG- YES »PGMNATA-NC o#FCUL-Ry FRINTER-SHR, 
FIL ES—®HOL FOROS/DNe 

PROGRAM NAME-ORDER 1,PGMDATA- YE S,ENDMSG-NC, 
DFFMTERM—1,CFFNDF-1,9FFSFNT-182, 

FIL ES-SCUSTNAME/NG/SHR ,CUSTSHIP /DG /SHRO 
PROGRAM NAME-ORDER 2yPGMDATA~ YES,END NSG-NCy 
OF FMT ERM-1,. CEFNDF 1,0FFSFDI- 212, 
PRUFLNG— 243, PRUFS7—-$7NRD I, 

FILES-cHOL CORDS/OU/SHRO 

PROGRAM NAME-ORDER 3, PGMDATA~ YE S;ENDMSG-NC, 
MRT MAX—4, NF FMTERM—4, CFFNDF-2,DFF SFO T-312, 
PRUFLNG—123, PRUF$Z-$2NRD2, 

FIL ES-DHOL CORDS/NU/SHR » INVENTR Y/DG/SHRO 
PROGRAM NAME-ORDER 4, PGMDATA-YES,ENDMSG-YFS, 
OF FMT ERM~1,CFFNN F-1,0FFSFNT-7C, 
PRUFLNG-30,PRUF$Z~$Z0RD3, 

FIL FS~CHOL CORDS /OU/SHR, INVENTRY/DU/SHRO 
PROGRAM NAME-ORDERP, PGMNATA—NO END NSG-YES,PRINTER-YES, 
FIL ES—pHOL CORDS/OU/SHRE 


Figure 8-28. Assignment Set Considerations 


$ZORD1 

C4#ZCRCISHPNM 2¥ xX RI 

FFGMNA¥0102007 7CcY ARNER? 
FCRCFRHO3Z01O121F ARNER NUMBER 
FOROANU 0316008 BEY 

FCUSTF OSOLOLSIF CUSTAMER NUMBER 
FCUSNG 0518006 8FY 

FCUSNMHO7TOIN121F CUSTOMER NAMF 
FSHPNMHO7 260071F SHT? 19 
FCUSNM 0901022 PEV 

FSHPNM 9926072 LEY 

FCUSAL 1001022 ery 

FSHPAL 1036022 LEY 

FCUSA2 11901922 geY 

FSHPA2 11746022 1EY 

FCUSA3 1201072 QFY 

FSHPA2 1226022 LFY 

FZIPCE 1ENgNse EY. 


TNFCRMATICN FOR UST CURING CCP ASSIGNMENT STAGE 


TRE FECIMAL LENCTE OF TEE FIFLD DESCRIPTOR TABLF IS 0182 
THF DECIMAL LENCTE OF TEE OUTPUT TEXT TS C399 
TRE DECIMAL LFNCTE OF THF INPUT TEXT TS C243 


Figure 8-29 (Part 1 of 3). Formats 
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$ZORD2 
C#7CRC2CTYL 2N X RI 


FFGMNAMO102007 TGV ORDERS 
FRRECCCO1LILOL2 TEY 
FCRONUMO3160081E 


FCUSNC O51800E1E 
FCUSNM 09010221€ 
FSHPNM 09360221E 
FCUSAL 10010221€ 
FSHPA1 10260221E 
FCUSA2 11010221E 
FSHPA2 11260221€ 
FCUSA3 12010221€ 
FSHPA3 12360221E 
FZIPCE 12E€00051E 


FLINEH 15010081F LINE NO. 
FCTYH 15140081F QUANTITY 
FITMH 15240081F ITEM NO. 
FCESCH 15 380111F DESCRIPTION 
FPRICEHIS660051F PRICE 

FLINT 1604002 3GY ol 


FCTY! 1614006 3GY 
FITML 1624008 3cy 
FLIN2 1704002 TEY 
fCTY2 1714006 TEY 
FITM2 1724008 TEY 
FOESC 1734022 TEY 
FPRICE 1789015 TEY 


INFORMATION FOR USE CURING CCP ASSIGNMENT STAGE 
TREE DECIMAL LENCTE OF THEE FIELD DESCRIPTNR TARLF TS C312 
THRE DECIMAL LENCTE OF TEE OUTPUT TEXT TS €513 
TEE DECIMAL LENCTt OF TEE INPUT TEXT IS C123 


$ZORD3 

c#20RrC3 2yY x R1 

FPGMNAMO 102007 7GY ORNER4 

FRRECNDO111012 TEY 

FCRDERMO2010291F PRESS ENTER TO CCBPLETE CRDER 


INFORMATICN FOR USE CURING CCP ASSIGNMENT STAGE 


THE DECIMAL LENGTE OF TEE FIELD DESCRIPTOR TABLE TS CC56 
TRE DECIM4L LENGTH OF TKE NUTPUT TEXT TS COTS 
THRE DECIMAL LENCTE OF TKE INPUT TEXT IS CC3C 


$ZORD4 


C$Z0RfC4QTYL 2N X RI 
F FGMNAMO 102007 7GY ORDER 
FRRECDDOIILOL2 TEY 
FLINL 1604002 BEY 
FETYL 1614006 3EY 
FITML 1624008 3EY 
FMESG 16340221E 
FLIN2 1704002 SEY 
FOTY2 1714006 BEY 
FITM2 1724008 SEY 
FOESC 1734022 eeyY 
FPRICE 1759015 8EY 


INFORMATICN FOR USE CURING CCP ASSIGNMENT STAGE 


ee ee ee ee ee a ee ae ee ee we ee 


THE DECIMAL LENGTH OF TEE FIELD DESCRIPTOR TABLE 1S OL68 
THE OFCIMAL LENGTH OF TKE NUTPUT TEXT IS 0225 
TEE DECIMAL LENGTH OF THE INPUT TEXT IS C123 


Figure 8-29 (Part 2 of 3). Formats 
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8-121 


8-122 


$ZORD5 


C#Z0RC5 2Y X R1 

FERRMS GO 1020201E 

FERRMS 201230021F 

FERRMS 3012701 S1F ORDER CANCELED 


INFORMATION FOR USE DURING CCP ASSIGNMENT STAGE 


TRE DECIMAL LENGTE OF TEE FIELD DFSCRIPTOR TABLE IS 0056 
THE DECIMAL LENCTE OF TEE NUTPUT TEXT IS cC5a 
TRE DECIMAL LERCTH OF THE INPUT TEXT IS CCCS5 


$ZORD6 

C4Zcree 2y xX RI 

FREAD] O30 10181F OROER 1S COMPLETED 
FPRICH O50 10061F AMOUNT 

FPRICE OSI70151F 

FEEAD2 060 10131F STATE TAX 

FTAXL Q6170151E 

FHEAD3 OTOIOL31F FEDERAL TAX 


FTAX2 O7170151E 

FREAD4 OB170151F aaa 
FTOTALH10010131F TOTAL 

FTCTAL 10170152€ 


INFORMATION FOR USE CURING CCP ASSIGNMENT STAGE 


TEE DECIMAL LENCTE OF TEE FIELD DESCRIPTOR TABLE IS 0070 
THE DECIMAL LENCTE OF THF OUTPUT TEXT IS C154 
TRE DECIMAL LENCTH OF TEE INPUT TEXT IS occs 


Figure 8-29 (Part 3 of 3). Formats 


After you have written a program which is to be run under 
the CCP, you must take steps to make it usable under the 
CCP: 


1. Compile or assemble the program to create an object 
module. 


2. Link-edit the object module. 


3. You may need to copy the program module to your 
production CCP disk pack or to the system pack 
that will be online by using the Library Maintenance 
program (S$MAINT). 


4, Prepare assignment specifications to include the 
program and the resources required by the program 
(such as disk files, terminals, and unit record devices) 
in one or more assignment sets in the assignment file, 
$CCPFILE, and execute the Assignment Build pro- 
gram (see CCP System Reference Manual). 


Before taking the preceding steps, be sure to read Disk File 
Considerations and Unit Record File Considerations, later 
in this chapter. 


Source programs cannot be compiled or assembled under 
‘CCP control. Programs may be compiled or assembled in 
the non-CCP program level of a DPF (dual partition) 
system; however, if the program is a recompilation of a 
program that is available to the CCP in the current assign- 
ment set, the new object module should be placed ona 

disk pack that is not being used by the CCP. New programs 
may be placed on a CCP program pack, but will not be 
available to the CCP until they are included in an assignment 
set. 


Note: 5704-SC2 supports an application development 
feature that allows new or modified programs to be 
catalogued online to an active CCP library on the system 
or program pack. By specifying EXECFIND-YES on the 
PROGRAM assignment statement, the program is located 
and catalogued in the library each time the program is 
requested, If this function is used extensively, system 
performance can be degraded because the program must 
be located each time it is requested rather than once at 
Startup. 


Chapter 9. Program Preparation 


COMPILING AND LINK-EDITING THE PROGRAM — 
MODEL 15 CCP 


Procedures for compiling or assembling a source program 

are given in the appropriate programming language reference 
manual (see Appendix C: Bibliography) or in IBM System/3 
Model 15 System Control Programming Reference Manual, 
GC21-5077. If the program is written in Basic Assembler 
language and uses CCP-provided macros ($Nxxx), the 

source program must be processed by both the Macro 
Processor and the Basic Assembler. 


The compilation (or assembly) output is a relocatable 
object module that must be link-edited to form a load 
module with a start address of X‘8000’. CCP Startup 
accepts only programs that are link-edited to start at 
X’8000’. If compilation and link-editing are to be 
performed as a single step (as they can be, in RPG II, 
COBOL, and FORTRAN IV), the start address is specified 
by using the LINKADD parameter on the // COMPILE 
OCL statement (LINKADD—8000). If compilation and 
link-editing are to be separate steps, the // PHASE Overlay 
Linkage Editor control statement must specify LINKADD 
—X‘8000’. Assembling and link-editing Basic Assembler 
programs must always be separate steps. RPG II, COBOL, 
and FORTRAN IV programs can be compiled and link- 
edited either as a single step or as separate steps, as 
determined by: 
RPG II — The entry in column 10 
(Object Output) of the 
RPG I! Control! Card 
Specifications 
COBOL and FORTRAN — The LINK operand of the 
PROCESS statement 


The maximum size of a user program under Model 15 CCP 
is 32K, including any program-appended storage area for 
DFF, but not including any additional storage for execution 
of memory resident overlay programs. Under 5704-SC2, 
external buffers can be defined and supported. The storage 
required for the external buffers is not included in the 
maximum 32K program size. See the /BM System/3 

Model 15 System Control Programming Concepts and 
Reference Manual, GC21-5162, for additional information 
on external buffers. 
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Programs which use 5445/3340 disk files must be compiled/ 
link-edited on a system of that disk-file type. This will 
enable the proper data management support to be included 
in the program. 


Notes: 


1. Programs running directly under Model 15 disk system 
management (not running under CCP) must be link- 
edited to start at X‘4000’. A halt occurs if these 
programs are link-edited at X’8000’. 


2. Programs that use indexed random add disk file 
access (IRA or IRUA — see index entry access value) 
for files that can be shared must be link-edited on a 
system that has been generated to support CCP. 


COMPILING THE PROGRAM—MODEL 10 AND 
MODEL 12 CCP 


Procedures for compiling or assembling a source program 
are given in the appropriate programming language refer- 
ence manual or in the /BM System/3 Models 10 and 12 
Control Programming Reference Manual, GC21-7512. 


RPG !!—Model 10 and Model 12 CCP 


During generation, the CCP copies the RPG II communica- 
tions service subroutines (SUBR90, SUBR91, SUBR9Q2, and 
SUBRQ3) to the disk pack specified by the PPUNIT-xx 
parameter of the $EPLG generation statement. This pack 
must be used to compile RPG II programs to run under the 
CCP. 


If unit record devices—MFCU, 1442 Card Read/Punch, 
3741 (data mode support only), 5203 or 1403 printers— 
were specified as being supported by the CCP, the CCP 

also copies special intermediary routines for unit record 
data management modules to the RPG II pack specified 

by the PPUNIT-xx parameter. These intermediary routines 
are named the same as the RPG II unit.record data manage- 
ment modules and the RPG I! modules are renamed. If 
unit record devices were specified, this pack cannot be used 
to compile RPG I! programs to run under disk system 
management (DSM) that use unit record devices. See Link 
Editing the Program, \ater in this section, for additional 
information. 
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COBOL and FOR1 RAN !V—Mcdel 10 and Model 12 CCP 


During generation, the CCP copies the COBOL and/or 
FORTRAN IV communications service subroutines 
(CCPCIO, CCPFIO) to the pack specified by the PPUNIT-xx 
parameter of the $EPLG generation statement for COBOL 
and/or the $EPLG statement for FORTRAN. 


If unit record devices-MFCU, 1442 Card Read/Punch, 
3741 (data mode support only}, 5203 or 1403 printers— 
were specified as being supported by the CCP, CCP genera- 
tion also copies special intermediary routines for the unit 
record data management modules to the COBOL or FOR- 
TRAN pack specified by the PPUNIT-xx parameter. These 
routines interface with the standard DSM modules; they 
are not replacements for the DSM modules. 


The COBOL and FORTRAN IV compilers permit you to 
choose, by means of a PROCESS statement: 


1. To produce a relocatable module that can be processed 
in a separate link-editing run (if the program uses unit 
record devices). 


2. To invoke the Overlay Linkage Editor automatically 
to produce a load module (if not using unit record 
devices). (See Link Editing the Program.) 


Basic Assembler—Model 10 and Model 12 CCP 


During generation, the CCP copies the CCP-provided 
macros ($Nxxx) to the pack specified in the PPUNIT-xx 
parameter of the $EPLG statement (LANG-ASSEM). 


If unit record devices—MFCU, 1442 Card Read/Punch, 
3741 (data mode support only), 5203 or 1403 printers— 
were specified as being supported by the CCP, CCP genera- 
tion also copies special intermediary routines for the unit 
record data management modules to the pack specified 

by the PPUNIT-xx parameter. These routines interface 
with the standard DSM modules; they are not replacements 
for the DSM modules. See Link-Editing the Program for 
additional information. 


If your. Basic Assembler program uses the CCP-provided 
macros, both the Macro Processor and the Basic Assembler 
program are required to process the source program prior to 
link editing. The $Nxxx macros must either be on the same 
pack as the Macro Processor or on the system pack. If your 
program does not use the CCP macros, you need only 
assemble and link edit the program. 


LINK-EDITING THE PROGRAM—MODEL 10 AND 
MODEL 12 CcP 


Link-editing is not a separate step when preparing an RPG II 
program to be run under the CCP, since RPG II compilation 
includes link-editing. Link-éditing is always a separate step 
in preparing a Basic Assembler program. 


When compiling COBOL and FORTRAN IV programs, 

you can specify that compilation and link editing be a 

single step by means of the LINK operand on the PROCESS 
statement. However, you must not choose to invoke the 
Overlay Linkage Editor automatically for programs that 
access one or more unit record devices (MFCU, 1442 Card 
Read/Punch, 5203 or 1403 printers). 


If the program being prepared was written in COBOL, 
FORTRAN IV, or Basic Assembler and accesses one or more 
unit record devices, you must enter // EQUATE Overlay 
Linkage Editor statements to cause the special CCP-provided 
subroutines to be inserted in the load module between your 
program and the DSM unit record data management modules 
your program uses, These statements must be in the following 
form: 


// EQUATE OLDNAME-$$xxxx,NEWNAME-$NXxxxx 


Figure 9-1 shows the OLDNAME- and NEWNAME- param- 
eters that must be used for various unit record files. Use 
Figure 9-3 and 9-4 to determine which DSM unit record 
data management modules will be used by your COBOL or 
FORTRAN program. 


You must not enter // EQUATE statements if the disk pack 
you are using for link-editing also supports RPG II, since 


the DSM modules have already been renamed. Figure 9-2 
shows the normal RPG II unit record data management 
module names and the CCP intermediary module names. 
Since the intermediary modules have the standard DSM 
module names in this case, no renaming is required. 


Overlay Linkage Editor Control Statements—Model 10 
and Model 12 CCP 


The following Overlay Linkage Editor control statements 
are used for COBOL, FORTRAN IV, and Basic Assembler 
programs that use unit record devices (see System/? 
Overlay Linkage Editor Reference Manual, GC21-7561, 
for complete descriptions of these statements}: 


1. Disk pack used for link-editing does not support 
RPG I! for CCP (see Figure 9-1): 


// PHASE... 
// OPTIONS... 
// EQUATE OLDNAME-$$xxxx,NEWNAME- 
$Nxxxx,UNIT-xx 
// EQUATE OLDNAME-@@xxxx,NEWNAME- 
$$xxxx,UNIT-xx 
// INCLUDE NAME-user program name,... (or relo- 
catable object deck) 
* // INCLUDE NAME-$$xxxx,. . . 
* // INCLUDE NAME-$Nxxxx, ... 


// END 
* The INCLUDE statements can be eliminated if: 
a. The data management modules reside on the same 
pack as the Overlay Linkage Editor. 
b. The UPACK- keyword is specified on the // 
OPTIONS statement. 


Example: Assume the following: 


a. Program SAMPLE resides in the relocatable library 
on Ri, 

b. Program SAMPLE uses the printer under CCP. 

c. The Overlay Linkage Editor and the data manage- 
ment modules reside on the same pack (R1). 

d. R2 is the pack to be used during a CCP run. 


The required Overlay Linkage Statements are: 


// PHASE NAME-SAMPLE,UNIT-R2,RETAIN-P 

// OPTIONS MAP-XREF 

// (NCLUDE NAME-SAMPLE,UNIT-R1 

// EQUATE OLDNAME-$$LPRT,NEWNAME-$NLPRT 
// EQUATE OLDNAME-@@LPRT,NEWNAME-$$LPRT 
// END 
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PECOREIDATE IARRGEMENE: FIRST / / EQUATE SECOND / / EQUATE 
epee NT OLDNAME-| NEWNAME- | OLDNAME- | NEWNAME- 


1442 card read/punch $SARFF $NARFF @@ARFF $$ARFF 
5203/1403 printer $$LPRT $NLPRT @@LPRT $$LPRT 
5424 MFCU read/punch $$MFRU $NMFRU @@MFRU $$MFRU 

Read/print $$MFRP $NMFRP @@MF RP $$MF RP 


Read only $$MFRD $NMFRD @@MFRD $$MFRD 
Punch only $$MFPU $NMFPU @@MFPU $$MFPU 
Print only $$MFPR $NMFPR @@MFPR $4MFPR 
Print/punch SSMFPP $NMFPP @@MFPP $$MFPP 
Full function $$MF FF $NMFFF @@MFFF $SMFFF 
Read $$CPIP $NCPIP @@CPIP $$CPIP 

Punch $$CPOP $NCPOP @@CPOP $$CPOP 





Figure 9-1. Unit Record Data Management Names to be used in // EQUATE Overlay Linkage Editor Statements for Model 10 and Model 12 
COBOL, FORTRAN IV, and Basic Assembler Programs Using Unit Record Devices (non-RPG II Disk Pack) 


2. Disk pack used for link-editing supports RPG II The required Overlay Linkage Editor statements are: 


for CCP (see Figure 9-2): : 
// PHASE NAME-SAMPL.E,UNIT-R2,RETAIN-P 


// PHASE... // OPTIONS MAP-XREF 
// OPTIONS... Object deck 
// INCLUDE NAME-user program name... (or /{ INCLUDE NAME-$$LPRT,UNIT-R1 
relocatable object deck) // INCLUDE NAME-$$UPRT,UNIT-R1 
* // INCLUDE NAME-$$xxx,... // END 


* // INCLUDE NAME-$$Uxxx,... 


Link-Editing a Program to Run Under DSM—Models 10 


// END and 12 

* See note under 1. Special considerations apply to link-editing programs to 
run directly under Model 10 and Model 12 DSM if unit 

Example: Assume the following: record devices are used in the programs and are also sup- 


ported by the CCP. 
. Program SAMPLE is a relocatable object deck. 
b. Program SAMPLE uses the printer under CCP. 


2 


c. The Overlay Linkage Editor resides on a pack RPG !!—Model 10 and Model 12 CCP 
separate from the data management modules. 
d. The pack to be used during the CCP run resides If unit record devices are being used by both the CCP 
on R2. RPG II programs and the non-CCP RPG I! programs, you 


must use separate disk packs for compiling the two different 
types of programs. If unit record devices are not being 

used in both the CCP environment and the non-CCP environ- 
ment, the same pack can be used for compiling both types. 
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Model 10 and Model 12 Unit Record ccP Model 10 and Model Device Option Statements 
Unit Record Data Data Management| Intermediary 12 Data Management| and Language Statements Used 
Management Function Module Module Module Name in a FORTRAN Program 
1442 card read/punch $$URFF $$ARFF SSAREF // READ DEVICE-1442 
5203/1403 printer $$UPRT $$LPRT READ (9,...)... 
5424 MFCU read/punch $$UFRU $$MFRU PUNCH DEVICE-1442 
Read/print S$$UFRP $SMFERP WRITE (9,...)... 
Read only $SUFRD $$MFRD ; 
Punch only $$UFPU $$MFPU PRINT DEVICE- ' 
Print only $$UFPR $$MFPR WRITE (3,...)... 
Print/punch $$UFPP S$MFPP CALL P1403(...) 
Full function] $$UFFF $$MFFF CALL $1403(...) 
Read $SUPIP $$CPIP CALL SP1403(... 
Punch $$UPOP $$CPOP CALL PRINT (...) 
CALL SKIP (...) 
Figure 9-2. Unit Record Data Management Names for All Languages, CALL SPACE (...) 
if the Pack Also Supports RPG |} for Model 10 and 
Model 12 CCP. // INCLUDE Overlay Linkage Editor READ DEVICE-MFCU2 
statements are required if the Overlay Linkage Editor is PUNCH DEVICE-MFCU2 
on a different pack from these modules. CALL READ (...) 


CALL PUNCH (...) 


READ DEVICE-MFCU2 
PRINT DEVICE-MFCU2 


Model 10 and Model 
12 Data Management 
Module Name 


Language Statements as they 
Appear in a COBOL Program 





READ (2,...) 
$$ARFF UR-1442-RD or UR-1442-PU WRITE (2,...) 
$$LPRT UR-1403-n-nnn or UR-5203-n-nnn CALL READ (...) 
‘ -RD- 
SoMa le ses ist . READ DEVICE-MFCU2 
uR-6424 ) Et -PU-n PUNCH DEVICE-MFCU2 
S$MFRP —_xjUR-5424 JB L-RD-n PRINT DEVICE-MFCU2 
s READ (2,...) 
UR-5424 {EL PR-n WRITE (2,...) 
$$MFFF ~(uR-5424 }E¢-RD-n CALL READ (...) 
B CALL PUNCH (...) 
UR-5424 }E! Pu-n 
P READ DEVICE-MFCU1 
UR-5424 s -PR-n READ (1,...) 
$$MFRD UR-5424 jot -RD READ DEVICE-MFCU2 
P) READ (2,...) 
$$MFPU UR-5424 18\ PU CALE REAO Rees 
_ $$MFPR UR-5424 JE{.PR CALL STACK (...) 
SSMFPP UR-5424 15¢ PI PUNCH DEVICE-MFCU2 
WRITE (2,...) 
* Hopper (P or S) and association value (n) are the CALL PUNCH (...) 
same in each statement. CALL STACK (...) 
PRINT DEVICE-MFCU2 
Figure 9-3. Unit Record Data Management Used by Model 10 and WRITE (2,...) 


Model 12 COBOL Programs 
PRINT DEVICE-MFCU2 


PUNCH DEVICE-MFCU2 
WRITE (2,...) 
CALL PUNCH (...) 





Figure 9-4. Unit Record Data Management Used by Model 10 and 
Model 12 FORTRAN Programs 


Program Preparation 9-5~ 


COBOL, FORTRAN IV, and Basic Assembler—Model 10 
and Model 12 CCP 


Different considerations apply to link editing COBOL, 
FORTRAN, and Basic Assembler programs to run directly 
under Model 10 and Model 12 DSM, depending on whether 
or not the disk pack used for link-editing contains the CCP 
intermediary routines for RPG II unit record data 
management. 


Pack Not Containing RPG I! CCP Intermediary Modules: \f 
‘unit record devices are used, no special INCLUDE or 
EQUATE statements are required for unit record data 
management modules. Therefore, automatic link editing 
can be done when compiling COBOL and FORTRAN pro- 
grams. 


Pack Containing RPG I! CCP Intermediary Modules: \f unit 
record devices are to be used, a separate link edit step is 
required, The required Overlay Linkage Editor control 
statements are: 


// PHASE... 

// OPTIONS .. 

// EQUATE OLDNAME-$$xxxx, NEWNAME-$$Uxxx 

// INCLUDE NAME-user program name,... (or relocatable 
object deck) 

// INCLUDE NAME-$$Uxxx,... 


* 


// END 


* See note under 1. 


Example: Assume the following: 


a. Program SAMPLE resides in a relocatable library 
on R1, 

b. Program SAMPLE uses the printer. 

c, The Overlay Linkage Editor resides on a pack 
different from the data management modules. 

d. The pack to be used for CCP execution resides on 
Ri, 


The required Overlay Linkage Editor statements are: 


// PHASE NAME-SAMPLE,UNIT-R1,RETAIN-P 
// OPTIONS MAP-XREF 

// EQUATE OLDNAME-$$LPRT,NEWNAME-SSUPRT 
// INCLUDE NAME-SAMPLE,UNIT-R1 

// INCLUDE NAME-$$UPRT,UNIT-R1 

// END 
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COPYING THE LOAD MODULE 


During CCP execution, the programs to be executed 

under the CCP must be on either the pack from which the 
CCP was loaded (// LOAD $CCP,xx) or the pack from 
which DSM was initially loaded (IPL’ed). If the compile and 
link edit processes did not cause the program module to 

be located in the object library of either of these packs, 

you must execute the Library Maintenance program to 

copy the module to the appropriate pack. 


MAKING ASSIGNMENTS 


To permit a new program to be executed under the CCP, 
the program must be defined in an assignment set. A 

// PROGRAM statement and possibly other statements must 
be added to at least one of the assignment sets, and an 
Assignment Build run must be made (see CCP System 
Reference Manual), 


You must provide the following information about your 
program to the person responsible for maintaining the CCP 
assignment sets: 


® {f the program uses the 3270 Display Format Facility: 


— Number of terminals in the program that use DFF 

— Number of display formats used by the program 

— Size of the largest Field Descriptor Table for display 
formats used by the program, rounded up to the next 
multiple of 256 (the size of this table is given in the 
printed output of the Display Format Generator) 


Note: See Assignment in CCP System Reference Manual 
for an example of calculating storage sizes. 


@ Disk file usage—disk file organizations and processing 
methods used (see Disk File Considerations); are disk 
files sharable (see Index entry disk file sharing)? 


@ Input and output communications record area sizes. 


@ Terminals used by the program and whether they are 
required:by the program in order to run or acquired by 
the program as it is running. 


@ Terminal attribute sets required for each terminal to be 
used in your. program. 


® Program type—SRT, MRT, never-ending, dedicated 
{runalone), reusable—if MRT, how many terminals can 
the program service at one time? (Dedicated and 
reusable types are defined for Models 10 and 12.) 


Program name. 
Prograrnming language used. 


The unit record devices used: 

— 5203 Printer (Models 10 and 12) 

— 1403 Printer 

— MFCU 

MFCM (Model 15 only) 

— 1442 Card Read Punch 

— 2501 Card Reader (Model 15 only) 

3741 Data Station Model 1 or 2 or Programmable 
Work Station Model 3 or 4 


Is data allowed with the program request? 


Whether or not this is a CCP/Sort program (5704-SC2 
only). 


Whether or not you want a message sent to a requesting 
terminal when either you release the terminal or your 


program goes to end of job. 


The priority of this program when executing (5704-SC2 
only). 


How much additional storage is desired for execution 
of memory resident overlay programs (Model 15). 


Whether or not this program is in the object library at 
CCP startup. 


If your program is written in either RPG II or FORTRAN 


and disk file buffer sharing is allowed (Models 10 and 12). 


@ You must not use the printer/keyboard (console) 
under the CCP except as a communications device, 
using CCP operations. 


@ A program using unit record devices compiled to run 
under the CCP will not run on a non-CCP system. 


See Link-Editing the Program, earlier in this chapter, for 
additional considerations for using unit record devices in 
COBOL, FORTRAN, and Basic Assembler programs. 


UNIT RECORD FILE CONSIDERATIONS—MODEL 15 
ccPp 


The following considerations apply to use of unit record 
devices (1403 Printer; MFCU; MFCM; 2501 Card Reader; 
3741 Model 1 and 2 Data Station and Model 3 and 4 
Programmable Work Station; 1442 Card Read Punch) by 
programs running under CCP and among the CCP partitio 
and non-CCP partitions: 


© |f your application program uses unit record devices, 


n 


CCP allocates the devices to your program before your 
program is allowed to run. Your program retains control 


of the devices until it terminates. 


’ @ In general, unit record devices cannot be shared by 


programs running under CCP; they can never be shared 


among programs running in the CCP partition and 
programs running in a non-CCP partition. If, however, 
the unit record device is being spooled in the CCP 
partition, the device is always available to CCP, but 
only to one application program at a time. Also, the 
printer may be shared, even when it is not spooled, by 


CCP application programs for which PRINTER — SHR 


UNIT RECORD FILE CONSIDERATIONS—MODEL 10 
AND MODEL 12 CCP 


The following considerations apply to use of unit record 
devices by programs running under the CCP and between 
the CCP and non-CCP program levels of a DPF system: 


@ A unit record device (1442, MFCU, 3741, 1403, and 
5203) cannot be shared by programs running under 
the CCP and cannot be shared by programs running in 
opposite levels of a DPF system. If the printer is 
spooled in the CCP program level on a Model 12, the 
printer can be shared by other programs in the CCP 
program level. If your CCP application program uses 
unit record devices, the CCP allocates the devices to 
your program before it is allowed to run. Your program 
keeps control of the devices until it terminates. If no 
program running under the CCP (or in the process of 
being loaded) requires a unit record device, the system 
operator can allocate the use of unit record devices to 
the non-CCP program level in a DPF system. 


is specified in the PROGRAM assignment statement. 


The CRT/Keyboard (console) can be used only as a 
communications device, that is, CCP operations must 
be used to perform I/O to the console. 


If you request a program that uses a unit record device 
other than a printer (that is, a punched-card device or a 
3741) and that device is not immediately available to 
the program, your request is rejected, whether or not a 
queue command is in effect. 
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DISK FILE CONSIDERATIONS 
Models 10 and 12 Considerations 


The following considerations apply to the use of disk files 
by programs running under Model 10 and 12 CCP: 


Multivolume Files: Multivolume disk files are not supported 
under CCP. 


Online Files: All files available to programs on the current 
run of CCP must be online (mounted on a 5444, 54465, or 
3340) and described by FILE OCL statements at CCP 
startup time. 


Disk File Names: \f two or more programs that are meant 
to execute in the same CCP run reference the same disk 
file, the file name used in each of those programs must be 
the same (except if symbolic files are used — see DISKFILE 
and SYMFILE assignment statements in the CCP System 
Reference Manual, GC21-7588, for additional information). 


Opening and Closing of Files: A\l disk files described by 
FILE and matching DISKFILE statements are opened during 
CCP startup according to the file organization and access 
methods specified at assignment time (see Determining the 
Disk File Access Value in this chapter). All files are closed 
during CCP shutdown. 


Index Sort: \f required, the index sort for index files is 
done during CCP shutdown. 


Accessing Records Added to an Indexed File: There are 
special considerations when using certain file organizations 
and processing methods during a CCP run. Figure 9-5 
iNustrates special considerations when records are added to 
an indexed file during a CCP run. 


Abnormal Termination: \f CCP terminates abnormally (for 
example, because of a power failure, processor check, or 
U-halt), CCP does not automatically close files. When an 
abnormal termination of CCP occurs, the CCP disk file 
recovery programs ($CCPRB for a Model 10, $RINDX for 

a Model 12) can be used to close all disk files, and optionally 
can be used to update the necessary file pointers so that 
records added during the previous CCP run can be accessed 
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in subsequent runs. See the CCP System Operator's Guide, 
GC21-7581, for a description of $CCPRB; the Model 12 
SCP Reference Manual, GC21-5130, for a description of 
$RINDX. 


Accessing Indexed Sequential Add and Ordered Indexed 
Files: Once an indexed sequential add or an ordered 
indexed file load is done by a program running under CCP, 
the file cannot be accessed by other programs during the 
CCP run until the program that first accesses the file closes 
the file. 


Sharing Files Between Program Levels: The rules for 
sharing disk files between program levels of a DPF system 
are: 


CCP Program Level Other Program Level 


Input file Can retrieve and update. 
Update file Can retrieve. 

Add file Cannot process file. 
Load file Cannot process file. 


Direct Files: A program running under CCP cannot create 
a direct file. When using a direct file, at least a dummy 
file (no records) must exist prior to the CCP run. 


Consecutive Updates to the Same Record: When file 
sharing is allowed (specified by the FSHARE parameter on 
the $EFAC generation statement), do not attempt to 
update the same record in succession without an intervening 
read of that same record within the program. 


Indexed Load Files: \f a disk file, defined as indexed-load 
access (access value 1O or |OU), is not loaded during a CCP 
run, the file exists after CCP shutdown but contains no 
records. 


Master Index: A master index for 5444 disk files is built 
by CCP based on the MSTRINDX keyword of the 
DISKFILE assignment statement (see the CCP System 
Reference Manual, GC21-7588). Therefore, you should 
not specify a master index in your application programs. 


Adding to a File by Two Programs: Two programs 
actually adding to the same file cannot run concurrently. 


Program 1 (P1) Program 2 (P2) Program 3 (P3) 


Accesses old records and 
records added during this CCP 
run, but does not add records 
itself (access value LTRANA or 
IRUANA for Model 10 and 
Model 12 CCP, IRA or IRUA 
for Model 15 CCP). 


Accesses old records Accesses old records 
in indexed file, FILEX, { (access value IR or 
and adds new records to IRU). 

the file (access value 

IRA or FRUA). 





(Note: Old records are records in the file prior to CCP startup.) 


Example 1: FILEX 










Pt loaded and executing (adding records) 
P2 loaded while P1 is executing 
P3 loaded while P1 is executing 


NF = not found 


Example 2: FILEX 


P1 loaded, adds records, goes to EJ 





P3 loaded, goestoEJ. — — — -~ W. 

P1 reloaded, adds more records, goes to EJ Newly Added 
: ly Added 

PS teloaded as: ae. eed ee ee ee baad 

P2 loaded. ee 


Note (Models 10 and 12): Another program 
of the same type as P1 cannot be loaded while 
P1 is executing. Two programs of this type 
cannot be executing concurrently. 


Figure 9-5. Accessing Added Records in Indexed Files Under the Cccp. 
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Consecutive Output Files: \f a file is defined with an 
access value CO (consecutive output), the program loading 
that file will overlay records loaded previously during the 
same CCP run. For example, suppose program 1 loads 

file 1 and goes to end of job. If program 1 is loaded again, 
any records added during the second execution will overlay 
records loaded during the first execution. 


Update Files: \f one program in an assignment set 
processes a file in update mode, that file is treated as an 
update file at CCP startup. Therefore, the following could 
occur: 


@ Program 1 processes file 1 as a direct update (DU). 
@ Program 2 processes file 2 as direct update. 


e@ At CCP startup, file 1 and file 2 are made identical by 
a FILE statement (// FILE NAME-FILE1,..., 
LABEL-FILE2). 


In this case, CCP startup cannot open file 2. Therefore, if 
different programs are to access the same file in update 
mode, they must both reference that file by the same 
name. 


Model 15 Considerations 


The following considerations apply to the use of disk files 
by programs running under Model 15 CCP: 


Multivolume Files: Multivolume disk files are not supported 
under CCP. 


Online Files: A\\ files available to programs on the current 
run of CCP must be online (mounted on a 5444, 5445, 
3340, or 3344) and described by FILE OCL statements at 
CCP startup time. 


Disk File Names: Different names can be used for the 

same file if the names are related to the file label by using 
the NAME and LABEL parameters of the F1LE OCL state- 
ment (see /BM System/3 Model 15 System Control Pro- 
gramming Reference Manual, GC21-5077, if operating 

under 5704-SC1; or /BM System/3 Model 15 System Control 
Programming Concepts and Reference Manual, GC21-5162, 
if operating under 5704-SC2, for additional information). 
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Opening and Closing of Files: A\\ disk files described by 
FILE and matching DISKFILE statements are opened 
during CCP startup according to the file organization and 
access method specified at assignment time (see Determining 
the Disk File Access Value in this chapter). Alll files are 
closed during CCP shutdown. 


Index Sort: The index sort for index files is done by using 
$CCPCL while CCP is running. CCP programs can access 
the file again during the current CCP run if the system 
operator executes the $CCPOP facility. See the /BM 
System/3 Model 15 CCP System Reference Manual, 
GC21-7620, and the /BM System/3 Model 15 CCP System 
Operator’s Guide, GC21-7619, for more information on 
$CCPCL and $CCPOP. 


Accessing Records Added to an Indexed File: Programs 
using certain nonadd disk access methods can access 

records added to an indexed file during the current CCP 

run even though the index sort has not been performed. 
However, the programs using the add access method must 
either CLOSE (for COBOL and Assembler) the file, or 
terminate (for RPG I!) before the program using the nonadd 
access method can open and use the file. These nonadd 
access methods are: 


® Consecutive input (CG) 
® Consecutive update (CU)—5704-SC2 only 
® Direct input (DG) 


® Direct input and update (DU) 


Unless the file is closed and reopened via the system 
operator $CCPOP/$CCPCL facility causing the index sort 

to be performed, the programs using nonadd access methods 
other than those in the preceding list cannot access records 
added to an indexed file during the current CCP run. See 
Determining the Disk File Access Value in this chapter for 
alist of the disk file access methods. 


Figure 9-5 illustrates special considerations when records 
are added to an indexed file during a CCP run. 


Abnormal Termination: \f CCP terminates abnormally 
(for example, because of a power failure, processor check, 
or U-halt), CCP does not automatically close files. When 
an abnormal termination of CCP occurs, the CCP disk 

file recovery program $RINDX, can be used to close all 
disk files and, optionally, update the necessary file pointers 
so that the records added during the CCP run that abnor- 
mally terminated can be accessed in subsequent runs. See 
the /BM System/3 Model 15 System Control Programming 
Reference Manual (5704-SC1), GC21-5077, or the /BM 
System/3 Model 15 System Control Programming Concepts 
and Reference Manual (5704-SC2), GC21-5162, for a 
description of the use of the file recovery programs. 


Sharing Files Among Partitions: When operating under 
control of 5704-SC1, the rules for sharing disk files be- 
tween partitions are: 


CCP Partition Other Partition 


Input file Can retrieve and update. 


Update file Can retrieve; can update if CCP 
update program processing this 


file is not currently executing. 


Add file Can retrieve or update nonadd 
records if CCP program adding 
records.is not currently executing. 
Can retrieve or update added 
records if CCP program adding 
records has gone to end of job 
and the system operator 
$CCPOP/$CCPCL facility has 
been run. 


Load file Cannot process file. 

When operating under control of 5704-SC2, the rules for 
sharing disk files using compatible access methods among 
partitions are determined by the SHARE parameter of 
the FILE OCL statement and the FILES parameter of 
the PROGRAM assignment statement. The compatible 
access methods allowed with file sharing across partitions 
are defined in the /BM System/3 Model 15 System Con- 
trol Programming Concepts and Reference Manual, 
GC21-5162. When operating under CCP, the compatible 
access methods allowed with file sharing across par- 
titions are defined in Model 15 CCP File Sharing Con- 
siderations in this chapter. 


Basically, the SHARE value of the FILE OCL statement 
has effect only across partitions, while the FILES param- 
eter of the PROGRAM assignment statement has effect 
within and across partitions. The relation between these 
parameters is shown in Figure 9-6; the symbol @ indicates 
that the program will be allowed to start. For example, if 
a batch program in a partition is using a file with SHARE- 
NO, then a program (including CCP startup) in another 
partition using that same file cannot be initiated. If CCP 
is started with SHARE-NO specified on the FILE OCL 
statement, that file is still considered shareable within 
CCP; the SHR/NOSHR value of the FILES parameter in 
the PROGRAM assignment statement determines whether 
the file can be shared and a second program initiated. 


Direct Files: A program can create a direct file if a direct 
output access file exists in the assignment set. 


Consecutive Updates to the Same Record: When file 
sharing is allowed, do not attempt to update the same 
record in succession without an intervening read of that 
same record within the program. 


Updating or Adding to Disk Files: When updating or adding 
to disk files, do not issue an Accept Input operation be- 
tween the reading and writing of a disk record if you intend 
to update or add the record. 


Indexed Load Files: \f a disk file defined as indexed-load 
access (access value |O or JOU) is not loaded during the 
CCP run, the file exists after CCP shutdown but contains 
no records. 


Master Index: \f operating under 5704-SC1, a master 
index for 5444 disk files is built by CCP based on the 
MSTRINDX keywork of the DISKFILE assignment state- 
ment (see the CCP System Reference Manual, GC21-7620). 
Therefore, you should not specify a master index in your 
application programs. 
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Consecutive Output Files (5704-SC1 Only): \f a file ina Consecutive Output Files (5704-SC2 Only): l\f a file is 
FORTRAN IV program is defined with an access value CO defined with an access value of CO (consecutive output), 
(consecutive output), the program loading that file will the program loading that file will overlay records loaded 
overlay records loaded previously during the same CCP previously during the same CCP run. For example, suppose 


run. For example, suppose program 1 loads file 1 and program 1 loads file 1 and goes to end of job. If program 1 
goes to end of job. If program 1 is loaded again, any is loaded again, any records added during the second exe- 
records loaded during the second execution will overlay cution will overlay records toaded during the first execution. 


records loaded during the first execution. More than one 
CO access can be done to a file and no récords are overlaid 
in RPG tl, COBOL, and Assembler programs. 
















OCL or 
Assignment 
Statement 

Value 







Current File Status 


ee 






Batch 
(using file) 





Program Trying to 
Start With Same File 





During startup, CCP is considered a batch program. 
>The file is assigned to a user task that is currently executing, 
The file is not assigned to any user task that is currently executing. 


Figure 9-6. File Sharing Across Partitions 
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Model 10 and Model 12 CCP File Sharing Considerations 


The following considerations apply when file sharing is 
allowed under Model 10 and Model 12 CCP (FSHARE 
parameter on the $EFAC generation statement): 


®@ Programs running concurrently under the CCP can 
update the same file. CCP protects the block of disk 
sectors containing the record to be updated until the 
program releases the block of sectors by writing the 
block to disk or reading another block. When programs 
are concurrently updating a disk file, a potential 
“lockout” condition could occur if a program does not 
release a block of sectors. 


For example, programs that read and update two or 
more files they share can be locked out of files if the 
following sequence of events occurs: 


1. Program A reads from file 1. 
2% Program B reads from file 2. 


3. Program A attempts to read from the same part 
of file 2, but cannot, because program B has not 
released the sectors. Likewise, if program B 
attempts to read from the same sectors of file 1 
that were read by program A, it cannot, because 
program A has not released the sectors. 


Because of this possibility, you should either code your 
program so that it does not do consecutive reads from 
different shared files without doing an intervening write 
to the first file, or if consecutive reads cannot be avoided, 
you should inform those personnel responsible for CCP 
assignments that the files should not be shared. 


@ When updating files, do not attempt to update (write) 
the same record in succession without doing an inter- 
vening read of that same record within the program. 
If you do, the task will be terminated. 


Programs defined at assignment time with access values 
IRUANA or IRANA can run concurrently (see Deter- 
mining the Disk File Access Value for the meaning of 
IRUANA and IRANA),. 


Two IRUANA or IRANA programs can access the same 
file concurrently. 


If a program defined as IRUANA or IRANA attempts 
to add records, it will be cancelled by the CCP. 


Figure 9-7 shows how two programs attempting to use the 
same disk file will interact. 


Model 15 CCP File Sharing Considerations 


Model 15 CCP allows concurrent access to a file by two or 
more programs whenever sharing is logically possible. Ifa 
program requires exclusive use of a file, NOSHR must be 
specified for the FILES parameter of the // PROGRAM 
assignment statement. 


CCP allows programs running concurrently to update or 
do indexed adds to the same disk file. CCP protects the 
block of sectors containing the record to be updated until 
the program releases the block of sectors by writing the 
block to disk or reading another block. CCP protects the 
add area of an indexed file when an add is requested. The 
file is not protected if a record-not-found condition occurs. 
This could cause the following sequence of conditions to 
occur: A record-not-found condition, followed by an 

add of that record, which might give a duplicate record 
condition if the record had been added by another 

CCP task. When programs are concurrently sharing a disk 
file, a potential lock-out condition could occur if a 
program does not release a block of sectors. 


Figures 9-8 and 9-9 show how two programs attempting to 
use the same disk file will interact. The following consider- 
ations and exceptions apply to sharing of nonexclusive disk 
files: ; 


@ An ordered indexed load must precede all other access 
and must be done only once during a CCP run. 


@ Double buffering is never done when files are being 
shared. CCP treats any double buffer accesses as 
single buffer accesses. 


@ A file processed as unordered indexed load can be 
shared serially, in time, with other unordered load 
accesses; however, no other types of-file access are 
allowed during the CCP run. 


®@ Consecutive load and consecutive add accesses cannot 
be done concurrently to the same disk file and neither 
access can be done concurrently with any other access 
of the same file. 


@ Indexed sequential addition to a file (with or without 
update) cannot be done concurrently with another 
access to that file. Indexed sequential addition cannot 
be preceded by any other indexed add access that 
actually adds records to the file, unless the system 
operator has initiated the $CCPOP/$CCPCL facility. 


® Consecutive output (load) to an existing file is treated 
by CCP as consecutive add, except in FORTRAN IV. 
Therefore, consecutive output can be done more than 
once to the same file during a CCP run, with results the 
same as consecutive add. In FORTRAN IV, consecutive 
output can be done only once to a file during a CCP run. — 
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@ An indexed file that has been added to, but has not 
yet gone through a key sort, can contain records that 
cannot be accessed by non-add indexed data manage- 
ments (see Disk File Considerations). 


@ Unlike indexed random add data managements (IRA 
and IRUA), indexed sequential add data managements 


(ISA and ISUA) do not search the area of added records. 


Therefore, a file opened ISA or ISUA can later be 
opened IRA or IRUA, but not vice versa. To opena 
file ISA or ISUA after a file has been opened IRA or 
IRUA, the system operator must execute the 
$CCPOP/$CCPCL facility. 


@ Programs that read and update (and/or add) to two or 
more files they share can be locked out of a file if the 
following sequence of events occurs: 

1. Program A reads from file 1. 

2. Program B reads from file 2. 

3. Program A attempts to read from the same part 
of file 2, but cannot, because program B has not 


released the sectors. Likewise, if program B 


File Already in Use 








attempts to read from the same sectors of file 1 
that were read by program A, it cannot, because 
program A has not released the sectors. 


Because of this possibility, you should either code your 
program so that it does not do consecutive reads from 
different shared files without doing an intervening write 
to the first file, or if consecutive reads cannot be avoided, 
you should inform those personnel responsible for CCP 
assignments that the files stiould not be shared. 


lf an MRT-NEP program uses file sharing and issues an 
accept input with no outstanding invite inputs, the disk 
file sectors protected from file sharing after the disk 
file was read are no longer protected. Under these 
conditions, if you try to add or update files, you get 

a disk error (invalid address). Before attempting to 
update files accessed by an MRT-NEP following an 
accept input, you must first retrieve the record to be 
updated. 


When updating files, do not attempt to update (write) 
the same record in succession without doing an inter- 
vening read of that same record within the program. 

If you do, the user task terminate with a OH halt. The 
program logic should be reviewed and corrected. 

















IS 
ISL IA 
CA IR ISU IRA ISA DO 
co cU cG 10 10U IRU ISUL IRUA ISUA (New DU DG 
File) 
ss Ss N N NN N N N 8 S 
SNe INN NN N N Y YY 
Ss YY Y Ss ON YY Y S ¥. x Y 
Pio rt—“‘“C;CSCOCUCNUU UN UN UNG UN NN N N N N N 
NN NN SN NN N N N___N 
NN Y Ss _N ¥--_¥ Y s N ¥ ¥ 
NN YS _N Yoo! Y S N ¥ Y 
NN Y _ S _N MN EY S N ¥ ae 
N N SS _N ss N# N# N S S 
PDort—“‘“(‘(‘;CCLNUOUNUNUNUN NN N N N N N 
SY YS. N Yo ¥ Y s Y Y Y 
KEY 

Y — Access permitted. 

N — Access not permitted. 

N# — Assecond access is not permitted because of DSM termination key sort first. 

Ss — Serialized access. First access must CLOSE within program before second may 


OPEN. 





Figure 9-7. Sharing Access to Disk Files—Model 10 and Model 12 ccp 
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File Already in Use IS 
(Open) As: ISL IA 





CA IR ISU IRA ISA DO 





Attempting 
to use (Open) File as? CO CU CG 10 1l0U IRU ISUL IRUA ISUA (New 





Ss S Ss N N N N N N N S S 
Ss Y Y N N N N N N Y Y Y 


; Y Y 
ISU, ISUL_ NN Y § N VY Y s N Y 
IA, IRA, [RUA 


ISA, ISUA_ [|N ON § S NSS N# NF UN ss 


DO 
| DU 
DG S Y Y S N Y Y Y S Y Y Y 
Y — Access permitted. 
Y*  — Direct output to an old or previously used file is treated as direct update. 
N  — Access not permitted. , 
N# — Asecond access is not permitted unless the file has been closed and reopened by 
the system operator. 
N@ — IO must be first access of file if used. 
S — Serialized access. First access must CLOSE within program before second may 
OPEN. 


Figure 9-8. Sharing Access to Disk Files—-Model 15 CCP (5704-SC1) 
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Attempting 
to Use (Open) 
File as: 


9° 
° 





ISUL 
IRUA 


ISUA 


co 
CA 
CU 
CG 
IS 
ISL , 
ISU 
iA 
ISA 
KEY 


On| sziz(/Zzi/ZizZzl2izj/2j2j2j2j), 2/2, 2, %)/%)/%)2 


Y — Access permitted. 
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oO 
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QO 
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File Already in Use (Open) As: 


1S 

ISL 

IR 

{RU IA 

ISU IRA ISA 


















































CG 10 10U. ISUL IRUA_ ISUA 
S N N N N N 
N N N N N 
Y N Y YY 
Y S N Y Y Y 
Ne N* N Ne NS Ne 
N N S N N N 
~y S N Y Y yi 
Y Ss N Y Y yi 
Y Ss N Y Y y! 
—y § N Y Y yi 
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oY al N Y ve Y 
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Y S N Y Y 5 
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N — Access not permitted. 
S — Serialized access. First access must CLOSE within program before 
second may OPEN. 


DO 


<1 <| 2 
m} & 


4/2) 2/2)2)/2 |2) 24) 4] =| 4) 41 4/?] 


<1 


DU 
DG 


z|<|<|< 
a 


<|<|<|«<|<|«<|<|<«|<]/z2 


lEiles accessed using the index sequential add access method under which adds have been made cannot be reopened using ISA 
unless the key sort has occurred, If any adds have been made and the key sort has not occurred, only random access methods 


can be used to add to the file. 


2The added records are not accessed if random add has occurred. 

Direct output to an old or previously used file is treated as direct update. 

A second access is not permitted unless the file has been CLOSED and OPENED by the system operator. 
51€ ordered indexed load access method is used, it must be the first access method used to access the file. 





Figure 9-9. Sharing Access to Disk Files—Model 15 CCP (5704-SC2) 
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Determining the Disk File Access Value 


When specifying the FILES keyword for the PROGRAM 
assignment statement (see CCP System Reference Manual), 
an access value must be given for each disk file. The access 
value indicates the mode of access of a disk file used by an 
application program. You should inform the person respon- 
sible for completing the CCP assignments of the type of 
organization and the access value for each disk file you 

use in your program. You can determine the access value 
for RPG It, COBOL, and FORTRAN disk file processing 
from Figures 9-10, 9-11, and 9-12. The access value symbols 
and their meanings are: 


co — Consecutive Output 
CG — Consecutive Input 
cu — Consecutive Update 
CA — Consecutive Add 
DG — Direct Input 
*DGA = — _Direct Input Binary Relative Record Numbers 
DU — Direct Input and Update 
*DUA — Direct Input and Update, Binary Relative 
Record Numbers . 
DO — Direct Output (valid only for Model 15 CCP) 
IS — Indexed Sequential Input Only 
ISA — !ndexed Sequential Input and Add 
ISL — {indexed Sequential Input with Limits 
ISU — Indexed Sequential Input and Update 
ISUL — Indexed Sequential Input and Update with 
Limits 
ISUA  — Indexed Sequential Input, Update, and Add 
IA — Indexed Sequential Add only 
IR — Indexed Random Input Only 
IRA — Indexed Random Input and Add 
IRU — Indexed Random Input and Update 
IRUA = — Indexed Random Input, Update, and Add 
10 — Ordered Indexed Load 
10U — Unordered Indexed Load 


**IRANA — Records which were added to the file by another 
program that has gone to end of job in the 
current CCP run will be read using Indexed 
Random Input and Add (IRA), but no records — 
will be added. 

**IRUANA- Records which were added to the file by 
another program that has gone to end of job 
in the current CCP run will be read and pos- 
sibly updated using Indexed Random Input, 
Update, and Add (IRUA), but no records will 
be added. 

*Valid for Mode! 10 and Model 12 CCP. For Model 15 
CCP, use DG or DU. 
**Valid for Model 10 and Model 12 CCP. For Model 15 
CCP, use [RA or IRUA. 
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The valid combinations of disk file organization (specified 
in the // DISKFILE assignment statement) and method of 
access (specified in the // PROGRAM assignment state- 
ment) are shown in the following chart. 


Method of Organization (// DISKFILE) 
Access —_—_— 
(// PROGRAM) Sequential Indexed 


Indexed Access Methods 
DU and DUA 
DG and DGA 
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INDEXED FILES 


Type of 
Processing 


Sequential* 


Sequential* 
(demand files 
processed by 
the READ . 
operation code 


Random 


Load 


Add records 
only 


k by Key, no ADD 
by Key,no ADD 
by Key, with ADD 
by Key, with ADD 
by Key, no ADD 
by Key, no ADD 


by Key, with ADD 

by Key, with ADD 

by Limits (RAF) 

by Limits (RAF) 

by Limits (RAF) 

by Limits (RAF) 

by Key, no ADD 

by Key, with ADD 

by Key, no ADD 

by Key, with ADD 

by Limits (RAF) 

by Limits (RAF) 

by CHAIN, noADD 
by CHAIN, with ADD! 
by CHAIN, no ADD 
by CHAIN, with ADD 


by ADDROUT 
by ADDROUT 
by ADDROUT 
by ADDROUT 


Unordered 
Ordered 


{ADD only 


* 


File Description Specification | 








File Addition/Unordered 


Number of Tracks 
for Cylinder Overflow 


Number of Extents 





Fite Type 








Length of Key Field or 









‘Record Address Type 




























































































































































































































































































































Filename Type of File Device Device Tape 
Organization Rewind 
Line or Additional Area ‘Index Fe oe Access 
zg gje ; 
. 8 E z urus_} Value 
£ git Entry x je 
3.4 5SI6/7 8 9 10 11 12 13 14115/16 — 62 63 64 65/66/67/68 69470]71 72173 74! 
of2 : Is 
013 | IS 
ola| [el 1 ISA 
fojs! | | ISA 
6 ISU 
: 7 ISU 
8 ISUA 
/o| 9 ISUA 
Ls]ol |e ISL 
Hf] bed ISL 
PTT tet ET ET TTI ( ISUL 
2 |r i ISUL 
3 is 
4 ISA 
ols Isu 
ole ISUA 
ol7 le| A t ISL 
jole| {Fl , ISUL 
ai ‘ : 
i A IRA 
f IRU 
PERLE ay ' IRUA 
of2| |r Models 10 
land 12 
—\" : Hi DGA 
tt DGA 
E DUA 
1a DUA 
: Al 10U 
| Alt D [ lo 
Omg | ela 
Ait) | ipusik || 1A 


























Sequential processing by key or limits must use the file index, which is always arranged in ascending sequence. When an indexed file 
is processed record-by-record from beginning to end, the file is processed through the index using the sequential-by-key method. 


Notes: 


1. 
2. 


DISK, DISK40, or DISK45 can be specified as the device (columns 40-46). 
If your system has 3340s attached, DISK is not a valid erftry in columns 40-46 since index files are not supported 
on the simulation areas. 
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Type of 
Processing 


Consecutive 
(The entire 
file is read 


from beginning 


to end.) 


Random 


Load 


Add records 
only 


: 


by READ —— § 


by CHAIN 
by CHAIN 


by ADDROUT 
by ADDROUT 
by ADDROUT 
by ADDROUT 


The file is written 
on disk as entered 
ADD only 


File Description Specification 




























































































































































































File Type Mode of Processing File Addition/Unordered 
F File Designation Length of Key Field or = tent Exit Number of Tracks 
End of File caf Record Address Eid ua 3AM for Cylinder Overflow 
Record Address Type Symbolic || Nameof_ Number of Extents 
Filename Sequence Type of File 3 Device Device 3 Label Exit 
File Format Organization a ‘= 
Line or Additional Area 3 Access 
ale e el Overflow Indicator] 2 os 
s S = Z| Block Record {5 Key Field | 3| Cor al 
E 2/2 Se Length | Zia Starting 12 
E als] j2l= Ss Q ion (ul 
io QTE lwlelc a 2zj> Location K Opt 
a4 5l6l7 8 9 10 17 1213 14|15}16]17| 19]19] 20 21 22 23 24 26 26 27] 28) 29 30] 31 {32133 3435 36 37 3e|30140 41 42 43 44 45 46]47 48 49 50 51 52 |53154 55 5g 61 62 63 64 65 |66/57]68 69) 70] 71 72 
ol2] JF ] F DA cG 
0/3] IF si Disk | cG 
ala] |r i Fi | | 1 L CG 
ols] |F F| | : ; |_| \ | cu 
ols! iF | L cu 
EH nce H Lee 
atts itt t t-+-+7++4 cu | 
fol Je 1c F l 
F lu 1 
F } 
ol2| (le tp 1 \ | 
o|3| iF 1S \ I 
+++ 
ofa] fel | | ly | DISIK 
os] |e us | | DISK 
T 
ole] |F [| 
of7| [F F US 
oja| |F 
of] IF F | | | CA 
1Jo; IF 
1 F I | i 
H4-EH | - 


































































































ZZ 12 OL 69 8 £9 99 59 ¥9 ES 79 LO 09 G5 8S 1S OS SS HS £5 ZS IS OS Gy Sb Lb Ob Sh by Eb ty lb OV EEE LES SC PERE TEE ORM Teiosesacareanaeeissbvecr 








Note: DISK, DISK40, or DISK45 can be specified as the device (columns 40-46). 
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7 File Description Specification 
Direct Files 
File Type Mode of Processing File Addition/Unerdered 


F File Designation Length of Key Field or xit Number of Tracks 












































































































































































































































































End of File of Record Address Field 3 tor Cylinder Overflow 
Record Address Type - |e, & 1 of Ex i 
Filename, Type of File “4 Device aa sau | ee 
File Format Organization s 8 
tin or Additional Area | 8 2 
2 Overflow Indicator] 2 
Type af s ES 3 Block Record vis on = 5 § 
SIS] | 1S] tenon sé oad | 
4 5/6]7 8 9 10 11 42 13 14/15] 16}17{18]19{20 21 22 24 25 26 271 28/29 30} 31 §32! 34]35 36 37 38/39] 40 41 42 43 44 45 46/47 48 49 50 51 52/53/54 55: 4 
Consecutive oj2| |F l F Sik) cG 
(The entire file ola| |r ! iF Dt me CG 
is read from ola] IF u DIL SIK cu 
beginning to oi | IF i D aK cu 
ole| |F CG 
end.) E } ; 
by READ ste 5 1 aa 
ole| |r [ 
ean eee t 
by CHAIN oj9| |r ane 1 [ R USK DG 
by CHAIN ‘ol F U F usik | bu 
F | Models 10 
Random by ADDROUT F | I 1 t and 12 Model 15 
by ADDROUT | |?! IF F | Us | DGA DG 
by ADDROUT | (2/3) JFL | | F RI | it VS Bus fF 
by ADDROUT | [14|_|F F \ i | Ee 
ols) le | rH DUA DU 
Disk addresses are | j°|6) |F | F WSK LI | DO (supported under 
Load developed for each | (9/7. |F I Model 15 CCP only} 
record entered. ols) iF t U + | 
aj9 F 1 i | 
iio |F ; 
++ 
F 
Zé LZ O£L 69 & 29 99 39 9 £9 ZO IG OS GG 8S £9 9G SG *S ES ZS 1S OG Br Br L¥ Sy GP PP fy Zh ih OF GE SE LE SE SE PE CE ZE LE OF HE BZ LZ BZ GE Pe ET? LerZeiboe 6 @ 4 9S PE TL 





* Records are inserted or changed in a direct file by defining 


the file as an update processed consecutively, or an update 
file processed randomly by the CHAIN operation code. 


Note: DISK, DISK40, or DISK45 can be specified as the device (columns 40-46). 
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File Description Specification 





RECORD ADDRESS FILES 





























































































































F File Type Mode of Processing File Addition/Unordered 
File Designation Length of Key Field or = Exit Number of Tracks 
fF Recor ‘i 3 M i Overt 
End of File oi rd Address Field e “ 3 for Cylinder ions 
Record Address Type Is ame o Number of Extents 
a Symbolic [4 : 
Filename Seculente Type of File g Device a ce 3 Label Exit 
File Format Organization ui a 
Line or Additional Area | 3| =| Index Access 
9! 
2 Overflow Indicator| 2} Values 
a gle $1 Block fecord 5 5 
a | 4 
| g e = Length . x ic Key Field | 2] Continua es 
E S18} lols beng |e =l5| Starting | 2 
iS SS ulate: 3 25 Location |4# K Option Entry 
34 sl6l7 8 9 1011 12 13 14]15| 16117] 18}19| 20 21 22 231 24 25 26 27|28{ 29 30] 31|32]33 34|35 36 37 38/39] 40 41 42 43 44 45 46 [47 48 49 50 51 52|53]54 55 56 57 5B SI 1 62 63 G4 65 
1. ADDROUT Fites ol2| |F ! F 3} | (i! h OLS 
pop 
o}3| |F | 
ote fealol i, | aa a se ee ee ee Ely ry 
2 Record Key Limits of4| |F | iR | IF | | EID ISK) 1 
ols! |F | | 
ae RELL ELT HH ! 
ol7| |F 
oe) IF 
O19 F 
10 F 
FE ' 
F 




































































* ADDROUT files may be associated with indexed, 
sequential, or direct disk files, 


* Record address files containing record key limits may only 
be associated with indexed disk files, but may be a disk 
or MFCU file. 


Note: DISK, DISK40, or DISK45 can be specified as the device (columns 40-46). 





COBOL LANGUAGE STATEMENTS 


ASSIGN | ACCESS 























DA-544x-S-name SEQUENTIAL OUTPUT 

UT-544x-S-name SEQUENTIAL OUTPUT 

DA-544x-S-name SEQUENTIAL INPUT 

UT-544x-S-name SEQUENTIAL INPUT 

DA-544x-R-name SEQUENTIAL INPUT 

DA-544x-S-name-U SEQUENTIAL 1-0 

DA-544x-R-name RANDOM ACTUAL INPUT 

DA-544x-R-name-U RANDOM ACTUAL 1-O 

“BA-544x-|-name SEQUENTIAL RECORD INPUT 

DA-544x-l-name SEQUENTIAL RECORD INPUT START... 
NOMINAL 

DA-544x-l-name-U SEQUENTIAL RECORD 1-0 REWRITE... 

DA-544x-|-name-U SEQUENTIAL RECORD 1-O START... 
NOMINAL REWRITE... 

DA-544x-l-name RANDOM RECORD INPUT 
NOMINAL 

DA-544x-Il-name-N RANDOM RECORD 1-O REWRITE 

NOMINAL 

DA-544-x-J-name-U RANDOM RECORD 1-O WRITE 

NOMINAL 





DA-544-x-I-name SEQUENTIAL RECORD OUTPUT 


Note: On systems with 3344 disk files, DA-544x can be replaced with DA-3340 for consecutive 
or direct files; DA-5445 can be replaced with DA-3340 for indexed files. 


Figure 9-11. Disk File Access Values for COBOL 


FORTRAN IV LANGUAGE STATEMENTS 


Device Option Input/Output Access 
Statement Statements Value 


// SEQ40 UNITNO-n, ... READ (...)... 
// SEQ44 UNITNO-n,... WRITE (...)... 
/{ SEQ45 UNITNO-n,... 


// DAD40 UNITNO-n,... 

// DAD44 UNITNO-n,... WRITE (...}... 

// DAD45 UNITNO-n, ... DEFINE FILE... 
FIND (...) 


*If the program only reads from the file, access value CG 
may be used. The file could then be sharable. 





Figure 9-12. Disk File Access Values for FORTRAN IV 
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After you have written a communications program to run 5. 


under the CCP, you will usually want to test the program 
before using it in a production environment. If the terminal 
devices to be used by the program are available, you can 
test the program according to the following general pro- 
cedure: 


1. Perform the procedures for program preparation 
described in Chapter 9, Program Preparation. 


2. Perform the CCP Startup procedures given in the 
CCP System Operator’s Guide. Include // FILE 
statements among the OCL statements at Startup 
for any test files that were described to the CCP at 
assignment time. 


3. Enter a request for the program from a terminal or 


from the system operator’s console. (See Program 6. 


Request in either the CCP System Operator's Guide 
or the CCP Terminal Operator’s Guide.) 


Chapter 10: Program Testing 


1f test files are to be printed using the Disk Copy/ 
Dump utility, the CCP must be shut down prior to 
using the utility, since the utility can neither be 
executed under the CCP nor in the opposite level 
from the CCP in a DPF (dual partition) system, as all 
test output data may not be available to it. (The 
Disk Copy/Dump utility program is described in 

IBM System/3 Model 10 Disk System Control 
Programming Reference Manual, GC21-7512; in /BM 
System/3 Model 12 System Control Programming 
Reference Manual, GC21-5130; and in /BM System/3 
Model 15 System Control Programming Reference 
Manual, GC21-5077, if operating under 5704-SC1, or 
IBM System/3 Model 15 System Control Programming 
Concepts and Reference Manual, GC21-5162, if 
operating under 5704-SC2. 


Evaluate the program by inspecting test files and 
other output from the program. 


Caution: Care should be taken during testing that a mal- 
4. Enter test input data as required by the program. function in the test program does not destroy other pro- 
grams or data in main storage. 


Program Testing 10-1 


10-2 


The CCP is adaptable to the concentrator and subhost 
functions in a teleprocessing environment: A combination 
of the two functions can be attained through application 
programming under control of the CCP. 


In a concentrator role, the CCP can gather data from a 
variety of terminals and forward the data to a host system 
(System/360 or System/370) for further processing. In 
the reverse direction, the CCP can collect data from the 


host system and distribute the data to a variety of terminals. 


In the concentrator role, the CCP supports user-written 
application programs to handle the message traffic in a 
store and forward manner. (Store and forward is defined 
as the interruption of data flow from the originating termi- 
nal to the designated receiver by storing the information 
enroute and forwarding it at a later time.) 


In a subhost role, the CCP can gather data from a variety 
of terminals, act intelligently on the data, and provide 
responses in most cases. {n those cases where additional 
data is required, the request can be forwarded to the host 
system for further processing. 


Appendix A: CPU to CPU Considerations 


The desirability of the concentrator function lies in 
reducing line and network costs and in retaining a consis- 
tent, common host interface in a changing terminal environ- 
ment. The subhost function has the same advantages as 

the concentrator function plus the advantages of distributed 
processing capability, fast response time, and back-up cap- 
ability (possibly degraded) in those occasions when the host 
system is unavailable. ‘In the concentrator and subhost 
roles, the CCP would most likely be attached to the host 

as a point-to-point or multipoint tributary station. 


The previous paragraphs have described the CCP in an 
online (nonswitched) connection to a host CPU. The CCP 
can also function in a switched environment where the 
CCP acts as a host during certain periods and, when neces- 
sary, functions as a subhost, connecting to a host CPU for 


‘ special transmissions or receptions such as transmission of 


batched data. The connection can be via a switched line 
defined as auto or manual call and auto or manual answer. 
If the host transmissions can be scheduled properly with 
the normal online terminal operations, an RPQ is available 
which provides a switching capability between a dial net- 
work for remote communications and multipoint control 
through the EIA local feature (IBM World Trade Corpor- 
ation EIA/CCITT). If two adapters are used, each can 
have this RPQ. Use of this RPO requires separate CCP 
startups and separate assignment sets for dial and multi- 
point operation. (See index entry switched lines for 
further information.) 


CPU to CPU Considerations A-1 


ATTACHMENT CONFIGURATIONS 


The CCP can be attached to the following IBM systems 
that have the indicated hardware and programming support: 


Communications Adapter | Programming Support 


BSCA RPG I 
Telecommunications 
BSCA 


Feature (data 
BSCA? 


mode support only) 
BSCA 








Remote Processor Configurations 












System/3 
Model 6 


Point-to-point 
Switched 
Multipoint tributary 
































RPG || Telecommunications' 
Feature (data mode 
support only) 


System/3 
Models 4, 
10, 12, or 15 


Point-to-point 
Switched 
Multipoint tributary 





















Multiline/ 
Multipoint 
(Features 
6030-6031) 


Point-to-point 
Switched 

Multipoint tributary 
Control station 






Point-to-point 
Switched 

Multipoint tributary 
Control station 








Programming support for 
RPOQ#S40076 and 

applications programming 
support 



















BSCA 
(RPQ#S840076) 


Point-to-point 
Switched 
Multipoint tributary 


System 7! 



























MLTA 
(RPG#S40065 ) 


BSCA 


1 Systern/7 with MLTA functions as a 2740 Model 1 with the following features: 
Checking — leased line. 
Dia! with checking — switched line. 
Station control with checking — multipoint tributary. 

2The Model 4 does not support MLMP. 


Programming support for 
RPO#S40065 and 

applications programming 
support 


Point-to-point 
Switched 

Multipoint tributary 
(see Note) 







System/360 and 
System/370 










BSCA Programming 
support (BTAM) 






Point-to-point 
Switched 
Control station 








PROGRAMMING CONSIDERATIONS 


This section provides an application-to-application under- 
standing of programming between the CCP and an attached 
CPU. 


The programming of an attached system for linkage to the 
CCP can differ greatly, depending upon the type of tele- 
communications support provided by the attached system. 
On the other hand, a particular application program running 
under. the CCP communicating with a CPU can be easily 
used with another CPU, with little or no change. 


A-2 


For BSCA attachments, the programmer of the attached 
CPU should be familiar with the System/3 Model 10 Disk 
System, System/3 Model 12, or System/3 Model 15 Multi- 
line/Multipoint (MLMP) support for an understanding of 
the base CCP data management and !OCS. (See the publi- 
cation /BM System/3 Multiline/Multipoint Binary Synchron- 
ous Communications Reference Manual, GC21-7573.) For 
MLTA attachments, the programmer of the attached CPU 
should be familiar with the MLTA Input/Output Control 
System for an understanding of the base CCP data manage- 
ment and |OCS. (See the publication /BM System/3 
Multiple Line Terminal Adapter RPQ Program Reference 
and Component Description Manual, GC21-7560.) 


The CCP application programmer must be aware that the 
CCP always considers the attached CPU to be a terminal. 
As such, the attached CPU must be identified as either a 
command mode or a data mode terminal. The attached 
CPU should be designated a command mode terminal if it 
is to initiate CCP application programs without CCP system 
operator intervention. If program initiation by the attached 
CPU is not required, it should be designated a data mode 
terminal. In this case, the CCP system operator or the 
operator of a CCP command mode terminal initiates the 
program. 


Command Mode 


As acommand mode terminal, the attached CPU is expected 
to provide certain commands in order to initiate a CCP 
application program and can optionally provide other 
commands to request special CCP control functions. The 
attaching CPU programming support must support variable 
length messages in order to handle CCP commands and 
responses. [Messages must be non-transparent, non-ITB, 
consisting of a single block followed by EOT. 


The following commands can be issued by the attached 
CPU to the CCP: 


/ON [password] (required) 

/Q (optional) 

/NOQ (optional) 

/FILE (dictated by requirements 
of the CCP application 
program) 

Program Request (required) 

/OFF (optional) 

/MSG (optional) 

/NAME (optional) 

/RUN (optional) 

Data Mode Escape (optional) 

/RELEASE (optional) 









E01, E02, E04, 
(RO1, RO2), £27 

E01, E02, E05, (R01, 
R02), £27, E29 
E01, £02, E05, (R01, 
R02), £27, E29 

E01, E02, E17, E18, 
E19, E20, E21, £26 
(RO1, RO2), £27, E29 
E01, E02, E08, E09, 
E10, (RO1, RO2), £27 
E01, E02, E22, E23, 
E24, E25, (RO1, R02), 
£27 

E01, E02, E06, (R01, 
R02), £27 

E01, £02, E07, (R01, 
R02), £27 

E01, E02, E16, (R01, 
R02), £27 

E01, £02, £11, E12, £13, 
E14, E15, (R07, R02), 
RO3, RO4, ROS, ROG, 
R07, ROS, ROY, R10, 
R11, R12, R13, R14, 
R15, R16, R17, R19, 
R20, R21, R23, R24, 
R25, R26, R27, £27, 
E28, E29, E30, £31, 
(RO1, RO2) 





A01, E03 















./Q A03 








. /NOQ A04 








. /FILE A0O6 





. {OFF 






. /NAME 













. /MSG A02 







. /RELEASE | AQ8 








. /RUN AOg 













User 
defined 


10. Program 
request 



















11. Data mode 
escape 
sequence 






Notes: 

1. RO2 cannot be received unless RO1 has been received. 

2. If message or response prefix is in italics, it can be 
received only under Model 10 and Model 12 CCP. If 
a prefix is in bold type, it can be received only under 
Model 15 CCP. 

3. Refer to the /BM System/3 Communications Control 
Program Terminal Operator’s Guide, GC21-7580, for 
a complete description of the commands and messages. 


Figure A-1. Command Mode Message and Response Prefixes 
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Attached CPU Application Program CCP 





Write CCP sign- 
on command 
/ON 













Read response 
from CCP 


Handle error 
response 












Write program 
request (program 
name) 


Issue error 
response 









Handle error 
response 


Error 
response 









(Determined by 
application.) 


Write CCP sign 
off command 
/OFF 














Response 
S03 


Read 
response 
from CCP 











Handle error 


Response 
response 


A10 


End of Job 


Figure A-2. Procedure for Issuing a Program Request from an Attached Command Mode CPU 


A4 


Receive and 
analyze sign-on 
request 


Issue response 
message 


Receive and 
analyze program 
request 


Request OK 


Initiate requested 
program 


Program sends 
initiated record 


Program 
EOJ 


Receive and 
analyze 
sign off 


Issue 
response 





Descriptions of the functions of these commands are given 
in the CCP Terminal Operator’s Guide, GC21-7580. The 
CCP Terminal Operator’s Guide also describes the responses 
given by the CCP to these commands. The attached CPU 
application program must analyze these responses and 

take appropriate action. All messages with an S prefix are 
suppressed by the CCP when communicating with an 
attached CPU. 


Figure A-1 shows the CCP commands and the prefixes of 
the possible responses to each command. Figure A-2 
iNustrates the general procedure that should be followed 
by the attached CPU application program in signing on to 
the CCP, issuing a program request, and signing off from 
the CCP. 


If a program running in a command mode CPU on a switched 
line has sent a /ON command, that program must issue a 
/OFF command to cause the line to disconnect normally. 
The /OFF command causes CCP to issue a response message 
to the program and disconnect the CPU before the line itself 
is disconnected. The program must be prepared to receive 
the response. If /OFF is not sent and a disconnection of 
the line occurs (caused, for example, by end of job on the 
command mode CPU), CCP attempts to issue a receive to 
the signed-on CPU on the disconnected line, and the CPU 
terminal is put into error recovery. 


Data Mode 


When an attached CPU is defined as a data mode terminal 
at CCP assignment time, programming of the attached CPU 
is greatly simplified, since it is not necessary to program for 
CCP application program requests and the possible CCP 
responses. In this case, however, the CCP application pro- 
gram must be initiated by the CCP system operator or 
another CCP command mode terminal. The initiated pro- 
gram can either specify the attached CPU as a required 
terminal (see PROGRAM assignment statement in CCP 
System Reference Manual) or acquire the CPU during 
execution. 


GENERATION CONSIDERATIONS 


The following generation statements must be considered 
when generating a CCP system that will support an attached 
CPU: 


$EMLA 
SEMLD 
$EBSC 
$EBSD 


All CPU-to-CPU support must be specified in the generation 
stage; a subset of the generated support can be selected in 
the assignment stage. See CCP System Reference Manual 
for descriptions of the generation and assignment statements. 


$EMLA and $EMLD Statements 


CCP to System/7 MLTA support must be described in these 
generation statements. When specifying the $EMLA 
parameters, you must decide whether or not translation is 
to be performed on the CPU-to-CPU messages. 


When specifying the parameters for the $EMLD statement, 
you must select one of the following System/7 types: 


e SYS7C 
@ SYS7SC 
@ SYS7DC 


The XMCODE parameter must be specified as PTTCEBCD. 


$EBSC and $EBSD Statements 


These statements are used to specify CCP to System/3, 
System/360, System/370, and System/7 BSCA support. 
When specifying the parameters of the $EBSC statement, 
consider what the physical attachment of the CPU will 
be: switched, nonswitched point-to-point, multipoint, or 
CCP as host (contro! station). 


The parameter for the |TB keyword should be YES if the 
CPU-to-CCP application program data blocks and data 
records are of fixed length and transmission checking is 
desired on each record. 


The RECSEP keyword should specify the record separator 
byte if the CPU-to-CCP application program transmissions 
are to be of variable block and record length. (Note: Block 
lengths can only be variable up to the maximum block 
length.) 


Either ASCII or EBCDIC code transmission must be 
specified for the CPU-to-CCP link. 


If CS is specified YES (control station) on the $EBSC 
statement, use of the RESPOL-YES parameter offers 
considerable performance improvement by making the BSCA 
polling routines resident. 
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If the MP-YES parameter is specified (multipoint tributary), 
the AUTORS-YES parameter offers performance improve- 
ment. 


The XPRNCY-YES operand should be specified if the 
full 256-character EBCDIC set is to be used in transmission 
between the CPU and the CCP application program. 


The TYPE operand of the $EBSD statement must specify 
CPU. 


Note: Record formatting for transmission using ITB, 
RECSEP, and XPRNCY applies only when the CPU is in 
data mode, communicating with the CCP application 
program. 


ASSIGNMENT CONSIDERATIONS 


The following assignment statements must be considered 
when making assignment selections for a CCP system that 
will support an attached CPU: 


// TERMATTR 
// BSCALINE 
// BSCATERM 
// MLTALINE 
// MLTATERM 
// PROGRAM 


The CCP assignment stage allows the user to select a subset 
of the generated options. The // TERMATTR statement 
must be used to specify the attributes of the attaching CPU. 
The // BSCALINE or // MLTALINE statements must be 
used to specify the characteristics of the line connection to 
the attaching CPU. The // BSCATERM or // MLTATERM 
statement must be used to specify the terminal character- 
istics of the attaching CPU. 
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The data transmitted by the CCP application program is 
formatted for line transmission {block length, record 
length, etc.) based on information specified in the 

// TERMATTR statement. Data transmitted to the CCP 
application program must be formatted in the same manner, 


RECOMMENDATIONS AND EXAMPLES 


It is generally recommended that, in CPU-to-CCP attach- 
ments, the remote CPU be defined as a data mode terminal. 
This greatly simplifies the attachment interface. In data 
mode, message synchronization is established by the 
application programs. 


In command mode, it is recommended that the CCP pro- 
gram be designed to send data first. The message length 
for the remote CPU read operations must be 82 characters 
minimum to handle command mode message responses. 


The examples on the following pages depict System/360/ 
370 BTAM-to-CCP data mode and command mode 
sequences. The BTAM operations are as follows: 


WRITE TI — Write Initial 
WRITE TQ — Write Inquiry 
WRITE TR — Write Reset 
WRITE TT — Write Continue 
READ TI — Read Initial 
READ TT — Read Continue 


Example 1: Multipoint Command Mode 

















BTAM 
Operation 


WRITE TI 


WRITE TR 


READ TI 


READ TT 


WRITE TI 


WRITE TR 


READ TI 


READ TT 


READ TT 


WRITE TI 


WRITE TR 


READ TI 


READ TT 


BTAM (Control Station) 


CCP (Tributary Station) 


Addressing sequence —————->- 
——— ACK 
S E 
T /ON[bpassword] T ————> 
x xX 
~<«——- ACK 


Addressing sequence ———__——>- 
<——— ACK 
S E 
T (program name) T —————>- 
x x 
<———— ACK 


Polling sequence ————--_——»>- 
<————- Program data or CCP error message 


ACK -————________—_> 
—<—-—=- More program data or EOT 


ACK 
se EOT. 


Addressing sequence -————»>- 
—_—— ACK 
S E 
T/OFF—_—_—_———___—_—> 
x Xx 
+ —— ACK 





Polling sequence ——_$_$_$_$_—$ ae 


~<———— T A10 SIGNED OFF — [HOLD/DROP] 


Xx TERMINAL E 
T 
Xx 





ACK -—————_________—_—_—_———- 
<——— EOT 
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Example 2: Point-to-Point Command Mode 


BTAM 
Operation 


WRITE Tl 


WRITE TR 
READ TI 


READ TT 


WRITE TI 


WRITE TR 
READ TI 


READ TT 


READ TT 


WRITE Tl 


WRITE TR 


READ TI 


READ TT 


BTAM ccP 


ENO -—— 
Z ~— ACK 


S 
T /ON[B password] us > 
Xx 


«ACK 


s E 
~<—— T A01 SIGNED ON — PROCEED T 
X Xx 





ACK -————>—______———_—— 
~<«— EOT 


ENO ——————________—_—_—>> 
«_— ACK 


E 
T (program name) T ————> 
Xx Xx 
—_ ACK 
EOT -——————— > 


—~<~— ENO 
ACK —————______—_—_— > 
—<—— Program data or CCP error message 


ACK ———____—_-__ 


t <—— More program data or EOT 
ACK 
EOT 
Ei —_—_—_—_—_—__-———- 
= ACK 


7 /OFF T ——————_—_> 
x Xx 
~~ — ACK 


EOT ———_————__—_————> 


~<—— ENO 
AK ————_—— > 


s 
~<——T A110 SIGNED OFF — [HOLD/DROP] 


x TERMINAL E 
T 
x 
BQ, ———_—_—“—_—l—nslyr-_- 
~<——— EOT 


Example 3: Point-To-Point Switched Command Mode 

















BTAM ccP 
Operation 


E 
WRITE Tl ID sequence N ———$$$_$____> 
a ~1!D sequence C 
K 
S E 
T/ON{bpassword] T —————> 


~<ACK 


WRITE TR EOT ———————————_— 
ENO 








READ TT ACK ——— 





$s E 
ae A01 SIGNED ON —PROCEED . 


READ TT AK —--—— 
~<-EOT 

WRITE TQ ENO ———————__———> 
~<ACK 


WRITE TT 









(program name) ees 


~«—ACK 


WRITE TR EOT ————___—_—__—_—_______» 
~<-ENO 


READ TT ACK —————————_________> 
~ Program data or CCP error message 


READ TT ACK ————— 
‘ 5 ~<—More program data or EOT 


READ TT ACK -——_—_—_—_—_—_—_——_————_— f 
~<EOT 


WRITE TO ENO -———————— 
~<—ACK 


WRITE TT Data to CCP 
application program ———_____»>- 








¥ ACK 


WRITE TR ET -———__-____—_____—_—_> 
~—ENO 
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Example 3 (continued) 


ern nen cn eee A 


READ TT ACK ——————. ome Program data 





READ TT L——————————— i 











~«— EOT 
WRITE TQ ENO —__—_—_—_> 
WRITE TT S E 
T/OFF T ——————__ 
x Xx 
~w— ACK 
WRITE TR EOT -—————$——$ $$ —______> 
~— ENO 
READ TT KK —— eo 
S E 
~<—T AiG SIGNED OFF — [HOLD/DROP] TERMINAL T 
Xx x 





READ TT | AC —————— ee OOOO 


| ~«— EOT 


Example 4: Point-to-Point Data Mode 


READ TI 


READ TT 


; 


READ TT 


READ TT 


End of Job 


ENQ -—> 

at ACK 
(Data) —————»- 

to ACK 


(Data) ———- z 
eee ACK 
(Data —————pe- 
eee ACK 


~——— ENO 
ACK een 
<~——— (Data) 


ACK -—> 
f ~+———- (Data) 


ACK ——-> 3 
~t————- (Data) 
AK > 


~«——. EOT 


PUT MESSAGE 
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For definitions of communications and data processing 
terms that are not included in this glossary, see /BM Data 
Processing Glossary, GC20-1699, or publications listed in 
Appendix C: Bibliography. 


SCCPFILE: A CCP contro! file on a 5444 disk or the 
3340 simulation area in which, during CCP assignment 
stage, the user defines one or more specific operating 
environments for the CCP. Each operating environment 
consists of a set of terminals, file, and programs that can 
be used during a particular run of the CCP. 


AID character: Attention Identification character. 


assignment stage: The special preparatory CCP run during 
which the user defines one or more sets of specific operat- 
ing environments in which the CCP can run. 


Attention Identification (AID) character: A code that is 
set in a 3270 display station when the operator takes an 
action that produces an I/O pending condition. The char- 
acter identifies the action or key that caused the condition 
to be generated. The AID is set when the display station 
operator presses a program access key, ENTER key, TEST 
REQ key, or program function key; when a Selector Pen 
attention occurs; or when a.successful operator identifica- 
tion card read-in occurs. It also identifies device addresses 
assigned to printers. 


attribute (3270): A characteristic of a display field. The 
attributes of a display field include: protected or unpro- 
tected; numeric-only or alphameric input control; displayed, 
nondisplayed, display intensified; selector-pen-detectable or 
nondetectable; and modified or not modified. 


attribute character (3270): A code that defines the attri- 
butes of the display field that follows. An attribute charac- 
ter is the first character in a display field, but it is not a 
displayable character. 


block mode operations: BSCA operations that result in all 
data from an operation in the program up to ETB being 
moved into or from the user program's record area. 


BSCA: Binary Synchronous Communications Adapter. 
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CCC: Copy Control Character. 


command interrupt mode: The operating mode of a termi- 
nal following data mode escape until the program execution 
is resumed by a RUN command (the terminal re-enters data 
mode) or until the program is cancelled by a RELEASE 
command (terminal enters command mode). 


command made: The operating mode of a command termi- 
nal following a successful sign-on, up to and including the 
program request. Following program termination, a termi- 
nal returns to command mode until another program request 
is made or until sign-off. 


command terminal: A terminal that is capable of command- 
ing CCP services related to requesting a program. Terminals 
are designated as either command terminals or data terminals 
at assignment time. 


communications management: A major function of the 
CCP that controls terminal input-output. 


communications service subroutine: A relocatable sub- 
routine provided by the CCP that is link-edited to user pro- 
grams written in RPG ||, COBOL, or FORTRAN IV. The 
subroutine is calted by the user program whenever the pro- 
gram requires a communications service, enabling program- 
mers to request communications services in these languages. 
Separate subroutines are provided for COBOL, FORTRAN IV, 
and RPG II; a macro is provided for Basic Assembler. 


control station: The primary or controlling computer ina 
multipoint telecommunications configuration. 


Copy Control Character (CCC): A character used in con- 
junction with the 3270 Copy command to specify that a 
particular operation, or combination or operations, is to 
be performed at a display station or printer in the data 
that is to be copied. 


Copy operation: A 3270 DFF operation that copies the 
contents of the buffer from one display station or printer 
to another display station or printer attached to the same 
control unit. 
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cursor. A unique symbol (an underscore) that identifies a 
character position in a 3270 screen display, usually the char- 
acter position at which the next character to be entered from 
the keyboard will be displayed. 


data entry application: A communications-based system 
application in which terminals are in relatively prolonged 
communication with an application program (as opposed 

to the typical inquiry application), for example, entering 
data for document preparation (such as invoice preparation), 
or entering data directly into data files from a terminal. 


data mode: The operating mode of a terminal when it is 
under control of a user program, until the program termi- 
nates, the terminal is released by the program, or the data 
mode escape characters are entered. While in data mode, 
a terminal is not in direct communication with the CCP. 


data mode escape: A special CCP command, consisting of 
a unique string of six characters entered at a requesting 
terminal while the terminal is in data mode. The data 
mode escape command temporarily suspends a terminal’s 
communication with a program and places the terminal in 
command interrupt mode, 


data terminal: A terminal that is not capable of command- 
ing CCP services. A data terminal is always either in stand- 

by mode (not polled for input by the CCP) or in data mode 
(under control of an application program). 


dedicated program: A program running under CCP that 
requires sole use of the CCP user program area. (Applies 
to Model 10 and Model 12 CCP.) 


designator character: A character that immediately follows 
the attribute character in a 3270 selector-pen-detectable 
field. The designator character controls whether a detect 
on the field will or will not cause an attention. For a non- 
attention-producing field, the designator character also 
determines whether the modified data tag for the field is 

to be set or reset as the result of a selector-pen detect. 


DFF: 3270 Disptay Format Facility of the CCP. 


disk system management: The group of system programs 
which control the operation of the IBM System/3 Model 10 
Disk System or the IBM System/3 Model 12 ard Model 15. 
Disk system management performs scheduling, input/output 
control, storage assignment, data management, and related 
services. 


DSM: Disk System Management. 
file management: A major function of the CCP that controls 


the use of data files by programs running under the CCP. 
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format find: A program (CGPFMT) that will find a newly 
created or modified format while running under CCP and 
additionally provides the capability to update the value of 
the DFFSFDT parameter of the PROGRAM assignment 
statement. 


generation stage: The initial stage of creating the CCP, 
during which the user specifies the size and range of 
function he requires in his verson of the CCP, and creates 
that version on his disk pack. 


implied Invite Input: An Invite Input that is not actually 
issued by the user program, but exists because data is 
allowed with the program request. Implied Invite Inputs 
are included in the count of outstanding Invite Inputs 

in the communications parameter list for certain operations. 


initial mode: The operating mode of a command terminal 
before a sign-on at the terminal has been accepted by the 
CCP. 


inquiry: A communications-based system application in 
which, typically, a single transaction or request for infor- 
mation is entered from a terminal and a response is 
returned to the terminal. 


inquiry-with-update: A communications-based system 
application in which records of transactions entered from 
terminals are used to interrogate and update one or more 
master files maintained by the system (synonymous with 
inquiry and transaction processing). 


interface: \n application programming under the CCP, the 
data areas (parameter list and record area), communications 
service subroutines, and defined operations by which user 
programs and the CCP communicate with each other. 


line buffer: The internal main storage area associated with 
a communication line from which data is transmitted to a 
terminal or into which data is received from a terminal. 
Data in this area includes device and line control characters 
inserted or removed by the CCP. 


master terminal name: \|n multicomponent terminals (1050), 
the symbolic terminal name specified during CCP assignment 
as referring to the principle input and output component. 


MDT: Modified Data Tag. 


message mode operations: BSCA operations that result in 
all blocks of data including the EOT signat being sent or 
received in a single operation, 


MLMP: Multiline/Multipoint BSCA IOCS, the base data 
management and lOCS included in the CCP for binary 
synchronous communications. 


MLTA: Multiple Line Terminal Adapter RPQ. MLTA IOCS, 
the System/3 programming support for the MLTA RPQ 
device, is included in the CCP for asynchronous (start-stop) 
communications. 


Modified Data Tag (MDT): A bit in the attribute character 
of a 3270 display field which, when set on, causes the field 
to be read on an input operation, The modified data tag 
may be set by (1) a keyboard input to the field, (2) a 
selector-pen detection in the field, (3) a card read-in opera- 
tion, or (4) program control. The modified data tag may be 
reset by (1) a selector-pen detection in the field, (2) pro- 
gram control, or (3) ERASE INPUT key. 


null character: A hex 00 character on a 3270 that occupies 
a position in the storage buffer and is displayed as a blank. 


MRT program: multiple requesting terminal program. 


multicomponent terminal: A class of terminals that can 
have more than one input and/or output devices attached. 
The 1050 system is the only terminal supported by the 
CCP that is considered to be a multicomponent terminal. 


multiple requesting terminal (MRT) program: A type of 
application program under the CCP that can process 
additional requests for it even though it is still processing 
an earlier request. 


NEP: never-ending program. 


never-ending program: A user application program which, 
after it has been initiated, normally remains in main 
storage and cloes not go to end of job until the CCP is shut 
down. 


operation stage: The stage of the CCP during which the CCP 
is started, supports an online network of terminals, and is 
shut down. , 


order entry application: A form of data entry application 
in which transactions (such as sales orders) are entered into 
a data file from remote terminals. 


output/input field: One of four classes of fields defined 
under the 3270 Display Format Facility. Output/input 
fields contain data that has been supplied either during 
format generation or during execution of the application 
program; this data can be changed by the termina! operator 
using the keyboard. 


password security option: An optional CCP feature, 
selected during generation, which requires a terminal opera- 
tor to enter a predetermined password before the CCP will 
allow the terminal to enter commands, 


physical file: See symbolic file. 


program management: The major function of the CCP that 
fetches programs, allocates system resources to programs, 
manages the concurrent execution of two or more programs, 
purges programs from main storage, and optionally main- 
tains a count of the number of times each application pro- 
gram is requested. 


program request: A command, consisting of a program 
name entered at a terminal or the system operator’s con- 
sole, that causes the CCP to initiate execution of an appli- 
cation program. 


program request count: The optional CCP program manage- 
ment function of maintaining a count of the number of times 
each application program is requested. 


program request under format (PRUF): A method of 
requesting a program from a display format on a 3277 or 
3275. The entire screen can be used to pass data with the 
program request. The name of the program to be requested 
appears as the first input field from the 3270 terminal. 


program-selected terminal: From the point of view of the 
application program, a terminal that is selected by an appli- 
cation program for input/output, as opposed to a terminal 
that requested the program (see requesting terminal). 
Program-selected terminals can be either required (must be 
allocated to the program before the program can run) or 
acquired (allocated dynamically to the program as it is 
running). 


program termination code: A two character code provided 
by the CCP when an application program has been cancelled 
by the CCP because of certain coding errors or program 
logic errors, or because the system operator requested can- 
cellation of the program. This code identifies the reason 
for the cancellation (refer to the CCP System Operator's 
Guide). . 


protected field: A 3270 display field for which the display 
operator cannot use the keyboard or operator identification 
card reader to enter, modify, or erase data. 


record mode operations: Application program input and 
output operations that result in a single record (for BSCA, 
a single record of a data block) being moved into or out of 
the program’s record area. 


requesting terminal: From the point of view of the applica- 
tion program, a terminal that requested the program, as 
opposed to a terminal that is selected by the program (see 
program-selected terminal), Requesting terminals are 
always command terminals. 
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RVI: A signal from a receiving device to a device that is 
transmitting to interrupt its transmission as soon as possible 
(see Get operation). 


selector pen detectable (SPD) field: One of four classes of 
fields defined under the 3270 Display Format Facility. SPD 
Tields allow the terminal operator to enter data by using the 
selector pen. 


Shutdown: The final stage of the CCP operation, during 
which the CCP allows programs currently executing or 
scheduled to finish processing, then closes files, adapters, 
and communication lines. 


sign-on: The procedure performed at.a terminal while it is 
in initial mode. This procedure may include entering only 
the /ON command, or entering the /ON command with a 
password or other user-specified security data. 


single requesting terminal (SRT) program: A type of appli- 
cation program under the CCP that can process a request 
from only one requesting terminal during its execution. 


SPD field: Selector Pen Detectable field. 
SAT program: single requesting terminal program. 


standby mode: The mode of a data (non-command) termi- 
nal when it is not under control of a user program. 


startup: The initial phase of the CCP operational stage, 

during which all necessary initialization occurs, including 
opening of disk files, adapters, and communication lines, 
and the completion of various tables and control blocks. 


subhost: A telecommunications system which, while directly 
controlling a group of terminals, is itself a tributary station to 
another central processor. 


symbolic file: A file reference (symbolic name) which 
allows, on separate executions of a program, reference to 
different files, known as physical files. A symbolic file is 
related by the terminal operator to a specific physical file 
by means of a /FILE command. 


symbolic subterminal name: Symbolic names assigned to 
individual components of a multicomponent terminal 
(1050). See master terminal name. 


system task: A unit of work for the processing unit from 
the standpoint of the CCP, consisting of a CCP function 
(as opposed to a user application, or user task) that must 
be performed by the CCP, such as communications 
management. 


task: See system task and user task. 
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task chaining: The process of requesting initiation of a CCP 
task from within a currently executing CCP task, without 
requiring system or operator action. 


task identification: An identifying character associated 
with a task which differentiates between that task and 
other tasks running concurrently under the CCP. 


terminal attributes: Characteristics of a terminal from the 
point of view of the CCP and CCP application programs, 
including block length, record length, data format, and 
other information. 


terminal reference identifier: A unique two-character 
identifier, assigned to-each terminal during the CCP assign- 
ment stage, that is used by the CCP and the system operator 
to refer to a specific terminal. Any of the 64 graphic 
EBCDIC characters may be used. 


translation: Under the CCP, conversion of the transmission 
line data code (if not EBCDIC) into EBCDIC or conversion 
from EBCDIC into transmission tine data code. 


tributary station: A secondary or non-controlling device in 
a multipoint telecommunications configuration. 


truncation: Loss of excess data when the length of data 
received from a terminal is greater than the maximum input 
length specified in the parameter list or when more data is 
provided in an output operation than the line buffer for 
the terminal can hold (in BSCA record mode output opera- 
tions, if the output length exceeds the record length speci- 
fied in the terminal attributes set). 


unit record device: Under the CCP, the MFCU, 1442 Card 
Read Punch, 5203 and 1403 printers, MFCM, 2501 Card 
Reader, and 3741 Data Station directly attached. 


unprotected field: A 3270 display field for which the ter- 
minal operator can manually enter, modify, or erase data. 


user task: A unit of work for the processing unit from the 
standpoint of the CCP, consisting of a user program (as 
opposed to a system function, or system task) that must 
be executed by the CCP. 


WCC: Write Control Character. 


Write Control Character (WCC): A character used in con- 
junction with 3270 write operations to specify that a par- 
ticular operation, or combination of operations, is to be 
performed at a display station or printer. 


The following publications contain information that readers 
may require to gain more detailed knowledge of System/3, 
teleprocessing, telecommunications equipment, and 
programming languages that can be used with System/3 

and the CCP: 
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@ /BM System/3 Communications Control Program 
General Information Manual, GC21-7578 


@ /BM System/3 Communications Control Program 
Terminal Operator’s Guide, GC21-7580 


@ /8M System/3 Models 10 and 12 Communications 
Control Program System Operater’s Guide, GC21-7581 


@ /BM System/3 Model 15 Communications Control 
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Table D-1 shows the decimal and hexadecimal values and 
RPG 11 codes that represent CCP communications opera- 
tions. The following symbols are used in the table to 
represent operations: 


Operation Symbols 
ACC Accept Input 
AcQ Acquire Terminal 
CPY Copy (3270 DDF only) 
EAU Erase All Unprotected (3270 DFF only) 
EOF —_ Force End-of-File (RPG II only) 
GET Get 
GTA Get Terminal Attributes 
INV Invite Input 
PNW Put-No-Wait 
PTG =. _—— Put- Then-Get 
PUT Put 
REL Release Terminal 
SHQ Shutdown Inquiry 
SPI Stop Invite Input 
TCH Chain Task Request (5704-SC2 only) 
WAT Wait Operation (Model 15 only) 


Operation Modifier Symbols 


CMD Command-mode Terminal 

BLK Block — send end-of-block (EOB) 

KPL. Keep line 

MSG Message — end end-of-transmission (EOT) 
NEL. Not End New Line 

NNL. Not Start New Line 

OVR Override (3270 DFF only) 

PRF Program Request under Format (PRUF) © 
RVI Send reverse interrupt (RVI) 

STA Set terminal attributes 
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PUT,MSG,NEL 306 | 0132 


PNW,MSG,OVR 2102 836 


PNW,MSG,OVR,PRF PUT,MSG,NNL 562 | 0232 


PNW,MSG,PRF PUT,MSG,NNL,NEL | 818 } 0332 


Operation Value RPG I 
 PNW.BLINNL | 550 | PUT,BLK 34 | 0022 ‘KBB 
806 PUT,BLK,PRF 98 | 0062 bKFB 
Fpuwmsc | a PUT,BLK,NEL 290 | 0122 BABB 
J enwascinv = | = | PUT,BLK,NNL 546 | 0222 bBBB 
} puwsc.inv.ove | — | PUT,BLK,NNL,NEL } 802 | 0322 bCBB 
} PNW.MSG.NEL | 310 | 0 PUT,MSG 50 | 0032 KCB 
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PTG PUT,MSG,OVR 2098 | 0832 


PUT,MSG,PRF 114 ; 0072 
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PTG,NEL 


PTG,NNL PUT,MSG,PRF,OVR | 2162 | 0872 


PTG,NNL,NEL 771 10 | OOOA 
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Table D-1 (Part 2 of 3). CCP Operation Codes 


This appendix contains summary tables of return codes 
issued to application programs by the CCP following tele- 
communications operations. (See index entry return codes 
for references to additional information.) The following 
summary tables are provided: 


Table E-1 Success/Exception Conditions Return Codes 

Table E-2 Common I/O Error Return Codes 

Tables E-3, Unique 3270, 3735, and 3741 BSCA I/O 

E-4,and E-5_ Error Return Codes 

Table E-6 Success/Exception Return Codes Per Opera- 
tion Type 

Table E-7 Common I/O Error Return Codes Per Opera- 
tion Type 

Tables E-8, 3270, 3735, and 3741 1/O Error Return 


E-9, and E-10 Codes Per Operation Type 


Table E-11 Contents of Effective Input Length Field 
and Record Area Per Operation Type and 


Return Code 


Tables 1-3 include a suggested program action for each 
CCP return code. The recommended actions are as follows: 


Recommended Program Actions 
Continue normal processing 


Attempt to determine the cause of the 

error and retry the operation if appropriate; 
otherwise go to the next logical operation 
Note: \f the failure that caused the error con- 
dition is not corrected before the retry, the 
same error may occur on the retry. 


Do not reissue the operation to this terminal 





Go to End-of-Job as soon as logically possible 


Process according to the requirements of 
the application 


Process data until EOT on the terminal for 
which data is pending 


Issuie a Get operation or go to End-of-Job 





Appendix E: Return Codes 


On data transfer operations, input and/or output data 
accompanies the following return codes, and no others: 


0, 1, 2, 3,6 


Negative Return Codes 


In most cases, when the CCP encounters an error condition, 
it stops processing the operation and returns a negative 
return code, Therefore, if concurrent error conditions occur, 
the CCP returns a code for only the first error condition 
detected, 


The results of the data transfer for any operation yielding 
a negative return code are unpredictable, except that a 
translation error on an output operation always indicates 
the data has not been transmitted. 


For BSCA, a negative return code always terminates the 
current transmission with the terminal, except for a 
translation error on a Put operation. Ifa translation error 
occurs when data is being sent to a terminal, the line is 
still connected to the terminal. Except for the translation 
error, a Put Message should not be issued if you are trans- 
mitting when a negative return code occurs and another 
Get should not be issued unless you wish to re-establish 
communication with the terminal, 


See Put-Then-Get operation under Operations in Chapter 2 
for information about the meaning of negative return codes 


for that operation. See also index entry return codes, 
negative (DFF). 


Use of Data Truncated Return Code in 3270 DFF 


The data truncated (hex 01) return code has a special 
meaning in programs using the 3270 Display Format 
Facility. If this return code is received from a Get or 
Accept Input operation, it indicates that the maximum 
input length given in the parameter list for the operation 
was less than the total length of all the fields the program 
should have expected, as defined by the last Put Message 
or Put Overrides (with select input fields) operation. 


Return Codes’ E-1 


The data truncated return code does not necessarily mean 
that more data was entered from the terminal than was 
received by the program. A situation could exist where 

only a few fields were entered from the terminal, the sum 

of which was less than the length the program should expect 
and less than the value given as maximum input length for 
the operation. The fact that the length given by the program 


CCP RETURN CODES 


Description 





0 0000 00 Successful operation 


1 0001 01 


is less than should have been given causes the data truncated 
return code to be returned from the operation. 


Under the DFF, the data truncated return code can be an 


indication that the program is expecting a record ina 
different structure than the one it is receiving. 


Program 
Action 


Al 


DATA TRUNCATED: Data was truncated; for input operations, A2 


the length of the data was greater than the input length specified 
in the parameter list; for output operations, the length of the 
data was greater than the length of the teleprocessing line buffer. 


2 0002 02 


EOT: Input operation was successful (EOT was received), Al 


or non-PRUF program request data was returned to a 
PRUF program at program request time. 


3 0003 03 


DATA TRUNCATION AND EOT: Data truncation occurred on A2 


this operation and EOT was received. 


4 0004 04 


SHUTDOWN REQUESTED: The system operator has requested A4 


CCP shutdown. The requested operation has not been performed. 


5 0005 05 


DATA PENDING: The operation was issued to a terminal ona A6 


BSCA line which is currently controlled by another terminal 

in use by your program (line awaiting EOT). An Invite Input was 
issued to a terminal which is currently awaiting an EOT. A Put 
or Get of a record or block was issued to another terminal on the 
same line. Put or Get operations with the previous terminal must 
be continued until EOT is transmitted on the line. 


6 0006 06 


TERMINAL INTERRUPT/RVI: A terminal interrupt (MLTA) A5 


or RVI (BSCA) has been received from the remote station. The 
operation was successful. For BSCA terminals, this return code 
indicates that the RVI was received after the initial positive re- 
sponse to addressing. An RVI to addressing will result in -14 for 
CPU, -40 for 3735, or -20 to -28 for 3270. 


7 0007 07 


3270 CLEAR: The terminal operator at 3270 pressed the CLEAR A5 


key (see 3270 Component Description, GA27-2749). 


8 0008 08 


TERMINAL NO LONGER AVAILABLE: Command interrupt A3 


mode was entered and the terminal operator released (/RELEASE 
command) the terminal. The terminal is no longer available to 


this program. 


Table E-1 (Part 1 of 2). Success/Exception Condition Return Codes 


E-2 


CCP RETURN CODES 


9 0009 09 TERMINAL OFFLINE: The requested terminal has been varied off- 
line and is not available to this program. 


Description 





10 000A 10 STOP INVITE INPUT SUCCESSFUL: The request to stop Invite 
Input was successful; the Invite input has been cancelled. 

11 000B 11 ACQUIRE TERMINAL FAILED: The attempt to acquire a terminal 
for this program has failed. 

12 000C 12 CHAIN TASK QUEUE FULL: The maximum number of chain task 
requests are already queued; this chain task request cannot be 
accepted. 

13 o00D 13 INSUFFICIENT TP BUFFER: Insufficient TP is available to queue 


this request. 


14 OOOE 14 CHAIN REQUEST DATA ACCEPTED SUCCESSFULLY: An opera- 


tion to accept the data from a chain task request was successful. 


15 OOOF 15 CHAIN REQUEST DATA TRUNCATED: The data associated with 
a chain task request was truncated. 


Table E-1 (Part 2 of 2). Success/ Exception Condition Return Codes 


Action 












Program 


A3 


Al 


Al 


A2 


A2 


Al 


A2 


Return Codes 


E-3 


CCP Return Codes 





Description Program 
Action 


-1 FFFF OJ DATA CHECK: Data was received incorrectly, checking A2 
error condition detected. 


-2 FFFE OK INVALID CHARACTER: (1) During translation of data, A2 
an invalid character was found. (2) An invalid ASCII 
character has been detected by BSCA. 


-3 FFFD OL LOST DATA: Data received was lost because it exceeded A2 
the size of the input buffer. 


-4 FFFC OM PERMANENT BSCA ERROR: Operation failed because a A2 
permanent error condition was detected. 


-5 FFFB ON ABNORMAL RESPONSE: An invalid response was received A2 
from the remote station. 


-6 FFFA 00 TRANSMIT/RECEIVE ABORT: Data transfer failed and the A3 
teleprocessing line has been closed. CCP has varied offline all 
terminals on this line. 


-7 FFF9 OP NO RESPONSE TO POLLING/ADDRESSING: The selected A2 
terminal does not respond to polling or addressing. 


-8 FFF8 0a TEXT TIME OUT: The terminal does not respond to attempted A2 
data transfer, 


-9 FFF7 OR WAIT TIME EXCEEDED: Data not sent or received before A2 
EQOT within a specified time frame. Note. If using 3270, 
retry (program action A2) is not allowed. Go to End-of-Job 
as soon as logically possible. 


-10 FFFG6 1 \ NO CONNECTION: Unable to establish a connection with A2 
the remote station. 

-11 FFF5 1J INVALID ID‘S: The 1D exchange with the remote station A2 
failed. 

-12 FFF4 1K ABORT, DISCONNECT: The switched line connection to A2 


the remote station has been lost. 


-13 FFF3 1L ADAPTER CHECK: A hardware check occurred on the A2 
teleprocessing line adapter. 


-14 FFF2 1M NEGATIVE RESPONSE TO ADDRESSING: The remote A2 
terminal has an error condition which prevents it from 
successfully receiving data. For the 3284, 3286 and 3288 
printer components of the 3270 system, this return code 
indicates the printer is busy. 


-91 FFA3 9J OPERATION NOT PERFORMED (RPG II SPECIAL): A2 
The operation was not performed because indicator 91 
was set on by a previous operation and was not set off. 


Table E-2. Common I/O Error Return Codes 
E-4 


CCP RETURN CODES 


-20  FFEC 
-21.  FFEB 
-22 FFEA 
-23  -FFEQ 
-24 -FFE8 
-25.  -FFE7 
-26  FFEG6 
-27 -FFES 
-28 FFE 
-29  FFES 





2K 


2L 


2M 


2N 


20 


2P 


20 


2R 







Description 
Device unavailable or not ready. 

Not used. This return code is not returned to the user. If Cccp 
detects this condition, an operations message is displayed 
followed by a 2F termination code. 

Equipment check; device end. 

3270 detected a BSCA error. 

Control check; data check. 

Data check on copy command. 

Operation check—copy command. 


Device busy with copy command. 


Control check, operation check, data check during copy 
command. 


Invalid data from 3270 using DFF. This return code is caused 
by the terminal operator pressing the TEST REQ key on the 
3270 keyboard. 


Table E-3. Unique 3270 BSCA I/O Error Return Codes 


Program 
Action 






A2 


A2 


A2 


A2 


A2 


A2 


A2 


A2 


A2 


Return Codes 


E-5 





FFD8 


FFD7 


FFD6 


FFDS 


FFD4 


FFD3 


FFD2 


CCP RETURN CODES 


4K 
AL 
4M 
4N 


40 


Description 


Attempted send before receive. 


Invalid character. 
Buffer overflow. 
Disk full. 
Directory full. 
Undefined header. 


3735 disk error. 


Table E-4. Unique 3735 BSCA 1/0 Error Return Codes 
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Program 
Action 






A7 


A2 


A2 


Ad 


AS 


A2 


A2 








CCP RETURN CODES 


-50 -FFCE 
-51  FFCD 
-52 FFCC 
-53 -FFCB 
-54 -FFCA 
-55 FF 
-56 -FFC8 
-57—-FFC7 
58 - FFC6 
-59 ~~ FFC5 
-60 FFCA 
-61 — FFC3 
-62. - FFC2 
-63  -FFCI 
-64 —-FFCO 
-65 FFB 
66 FFBE 


BN 
50 
SP 

50 
BR 
6} 

6J 

6K 
6L 
6M 
6N 


60 


Description 


Transparency error occurred. 


“No activity in 20 seconds. 


Data check. 

Received line bid error. 
Wrong length error. 
Reset was pressed on 3741. 
Security check. 

Disk overflow. 

Bad extent error. 

Both stations transmit. 
Length error. 

No record found on disk. 
Seek error. 

Read error. 

Write error. 

Not ready. 


Diskette write protected. 


Table E-5. Unique 3741 BSCA I/O Error Return Codes 
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Action 
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A2 


A2 


A5 


AS 


AS 


A7 


A2 
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A2 


A2 


A2 


A2 
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' This specifies that the Get operation was successful while the Stop Invite Input failed. 

The count of Invite Input operations outstanding for this user program is returned in the effective input length field of the parameter list. 
3 Indicates shutdown not requested. 

If a PRUF program, indicates that non-PRUF data was received. 
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(Abbreviations are explained under Operation Codes Appendix D) 
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Ps ees 
tah 
ae 
eae 
=p 
ee 










x x 


ele 
eee 





X 


[als 

-8 | FFF8 
[arn 
Palm 
ff 
rm 


x 








x 
x 
x 
x 


Et : 
Ble 
px p< | x 

x |x | x | 
x 

~ 


Invalid IDs 





Abort, disconnect 












a4] FFF2 Som | Negative response to addressing 
jn} fo | Operation not performed? 


1 Data check cannot occur on a Put for BSCA EBCDIC. 
2 RPG II SPECIAL only. 





es 
Ea 
x< 
x 
x 








OL-a 


edAt uoriesedO seq SePOD UUNIEY 10424 0/1 OLZE “8-3 F14EL 


pc] | ero rem nl en ew 
steele femme fp | Pep 
o|reo| 2 [mms ai, 
fra [omens Oe 
fa[ro| x [amore 1 | ete] | 11d tT 
En ce 


-25 | FFE7 Data check on copy command 





FFES = Deve busy with cop command CoE 
FFE4 Control, operation, or data check on 
copy command 
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Description 





Operation 
(Abbreviations are explained under Operation Codes in Appendix D) 
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Return Code Value 






~58 | FFC6 50 


FFCS 5R 





-60| FFC4 | 6} 
FFC3 | 6J 


-62 | FFC2 6K 








Description 


Data check 

Received line bid error 
Wrong length error 
Reset was pressed on 3741 
Security check 

Disk overflow 

Bad extent error 

Both stations transmit 
Length error 

No record found on disk 
Seek error 

Read error 

Write error 

Not ready 


Diskette write protected 
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(Abbreviations are explained under Operation Codes in Appendix D) 


srr ro rr ein [ew 
Se 
No activity in 20 seconds Xx ee alta ot 





Lee eel 
Peee ORAS 
Pe eee nd 


X 




















ah 
a 





























































































































































































Operation 
Return Code EFFL RECA EFFL RECA EFFL RECA EFFL RECA EFFL RECA| EFFL RECA EFFL RECA EFFL RECA 
LIN DATA ATRID NC NC NC NC NC LIN DATA LIN ATTRS NC NC 
1 — Truncated LIN’ DATA" EIN ee 
" LIN** | DATA** LIN** | DATA** | LIN* DATA* 
a rie 2 
3 — Truncated—EOT: un* | pata* LIN* | DATA* 
NC NC 
4 — Shutdown ZERO | BLANK 
A NC NC 
5 — Data pending FERO | BLANK 
NC NC 
t= GEEAR Key ZERO | BLANK ZERO | BLANK | 
& ‘ —t 
8 — Releasecl NG NC 
#INV | BLANK #INV | BLANK 
. " NC NC 
9 Jecminal off ling NC NC NC NC NC NC ZERO | BLANK NC NC 
fi + 
10 — Stop Invite Input Zeno | BLANK 
41 — Acquire failed NC NC 
1 - 
12 — Chain queue full 
13 — Insufficient 
TP buffer 
14 — Chain data 
accepted LIN DATA 
15 — Chain data 
truncated LIN" | DATA* 
-n — All negative 
return codes ZERO | BLANK NC NC NC NC ZERO | BLANK 
s ——_| | 





















LIN = 
LIN* = 
LINe* = 
#INV = 
NC = 
ZERO = 
ATRID = 
j DATA = 


DATA** = 
BLANK = 


RECA 
ATTRS) = 





Not applicable for DFF. 


DATA* = 


Actual length of input data received in the record area. 


Data was truncated — the value shown is the maximum input length. 


Data was truncated — the value shown is the actual length of data received in the record area. 


Count of outstanding Invite Inputs. 
No change. 

Set to zero by the CCP. 

Attributes Identifier. 

Data received from terminal. 


Data received from terminal up to maximum input length. 


Data received from the terminal, up to the last field that would fit in the record area. 


Set to blanks (X‘40‘) by the CCP. 
Terminal attributes information (21 positions). 


‘The top symbol is for non-DFF programs; the bottom symbol is for DFF programs. 





Table E-11 (Part 1 of 2). Contents of Effective Input Length Field and Record Area Per Operation Type and Return Code 


Return Codes 
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Operation 








PUT REL SHO spt! TCH WAT 











Return Code RECA | EFFL RECA EFFL | neca EFFL RECA EFFL | RECA EFFL RECA | EFFL RECA 









NC 
DATA NC NC #INV NC NC NC LIN NC NC 
NO 


1-T NOl 
tuncated DATA’ | NC NC LIN* 

















































- — —— 
2-E - — —= 

OT/Non-PRUF data | | oN | DATA LIN 

a 

3 — Truncated—EOT Un: | data‘ LIN? 
4—Shi 

jutdown NC NC 

ass oo = Ae-eeeniet 
f NC NC 
Bs Data'pending NC NC NC NC NC NC 
pe 

Be RN NC NC NC NC 










































Ps 2 
NC 
-—CL oo a anaes 
TS ERA ACY | ZERO | NC ZERO | BLANK 
8 — Released SERGE 
9 — Terminal offline Nc NC — — 
10 — Stop Invite Input ee 
11 — Acquire failed 
42 — Chain queue full 
13 — Insufficient 
TP buffer 


14 — Chain data 
accepted 











15 — Chain data 
truncated 








-n — All negative 
return codes 

















Legend: 
LIN = Actual fength of input data received in the record area. 
LIN* = Data was truncated — the value shown is the maximum input length. 
LIN** = Data was truncated — the value shown is the actual length of data received in the record area. 
= Count of outstanding Invite Inputs. 
NC = No change. 


ZERO = Set to zero by the CCP. 

ATRID Attributes Identifier. 

DATA Data received from terminal. 

DATA* Data received from términal up to maximum input tength 

DATA** Data received from the terminal, up to the last field that would fit in the record area. 
BLANK Set to blanks (X‘40") by the CCP. 

ATTRS = = Terminal attributes information (21 positions). 


RECA 


EFFL #INV 





‘The top symbol is for non-DFF programs; the bottom symbol is for OFF programs. 
‘The top symbol is for the Put portion of the operation; the bottom symbol is for the Get portion of the operation. 
I Not applicable for DFF. 





Table E-11 (Part 2 of 2). Contents of Effective Input-Length Field and Record Area Per Operation Type and Return Code 


$$CCPFILE 

$$CCPFILE, definition  B-1 
$$CCPFILE, generation 1-1 
$CCPAU 7-16 

$CCPDT 8-61 

$CC4Z9 =—-7-16 

$ECOM macro 7-19 
$ECPL macro 7-19 
$EEQU macro 7-19 
$ETNT macro 7-19 
$ETRC macro 7-19 
$ETUB macro 7-19 
$NCltO macro 7-8 

$NCIO macro, examples of use 7-12 
$NCOM macro 7-1 
SNOPV macro 7-3 

SNPL macro 7-6 

$NPLO macro 7-2 
SNRTV macro 7-3 

$SIT macro 2-16 

-91 return code 6-5 
/FILE command 3-16 
/NOQ cornmmand = 2-1 
/OFF command 3-20 

/Q command 2-1 
/RELEASE command 2-3 


ACCEPT (COBOL programming restriction) 4-15 
Accept Input operation 2-27 
' Accept Input operation, count of 
outstanding Invite inputs 2-27 
Accept Input operation, data with 
program request 2-28 
Accept Input operation, maximum 
input length 2-27 
Accept Input operation, MRT programs 3-3 
Accept Input operation, never-ending 
program 3-4 
Accept Input operation, put with Invite 
input consideration 6-11 
Accept Input operation, relation to 
Invite input 2-27 
Accept Input operation, RPG Il 6-12 
Accept Input operation, when allowed 2-27 
Accept Input operation, 3270 DFF 8-53, 2-27 
Accept Input, for chain task requests 2-28 
access value 
access value, disk files 9-17 
Acquire Terminal operation 2-34 
Acquire Terminal operation, multicomponent 
terminals 2-6 
Acquire Terminal operation, RPG If 6-12 
Acquire Terminal operation, RPG II, 
operation code 6-12 
Acquire Terminal Operation, set 
attributes 2-34 


Index 


Acquire Terminal operation, use of third 
parameter list field 2-3 
adding records to disk files 9-8, 9-10 
address of CCP user programs 
(Model 15) 9-1 
address of the record area 2-4 
address table 
address table, relocation 7-17 
AID character 
AID character, definition B-1 
AID character, input record format 
(3270 DFF) 8-20 
allocation 
application programs, system resources 
(see CCP System Reference Manual) 
BSCA line 2-13 
BSCA switched line 3-17 
MLTA lines 2-11 
MLTA switched lines 3-20 
status (Get Attributes) 2-31 
terminals 2-1 
alphameric data, defining (3270 
DFF) 8-17 
alphameric field 
alphameric field, characteristics 
(3270 DFF) 8-5 
alphameric field, characteristics (3270 
DFF), by field type 8-6 
alphameric field, RPG I! EXIT/RLABL 
interface 6-25 
answering a call on a switched line 3-17 
application program 
application program, allocation (see 
CCP System Reference Manual) 
application program, examples of 
logic 3-8 
application program, standard interface 
to CCP 2-1 
APPLY CORE-INDEX 
APPLY CORE-INDEX, COBOL progrmming 
consideration 4-15 
array 
array name (RPG Il) 6-9 
array, parameter 
array, parameter, extension specifications 
(RPG Il) 6-9 
array, parameter, FORTRAN = 5-2 
array, parameter, loading (RPG II) 6-9 
ASCII data 
ASCII data, translation 2-8 
assembler macro support mnotes 7-14 
assembler programming for CCP 7-1 
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disk file considerations 9-10, 9-12 
loading the RPG II parameter array 6-9 
lockout condition (disk file caution) 9-13 
logic error (program errors) (see 
CCP Messages Manual} 
logic of application programs (examples) 3-8 
look ahead fields 
RPG II programming consideration 6-31 


macro instruction (BAL) 
symbols used in defining 7-1 

macro mnotes (BAL) 7-14 
macro processor, correct version 

touse 7-1 
main file description (RPG II SPECIAL) 6-8 
making assignments (program preparation) 9-6 
management of tasks, files, programs 

(see CCP System Reference Manual) 
manual ariswer 3-17 
manual call 3-17 
master index 


COBOL 4-15 
considerations 9-8, 9-11 
RPG Il 6-31 


master terminal name, definition B-2 
maximum input length 
Accept Input operation 2-27 
COBOL 4-7 
FORTRAN — 5-5 
Invite Input operation 2-26 
RPG II EXIT/RLABL 6-26 
standard parameter list entry -4 
Stop Invite Input operation 2-29 
maximum number of fields in a display 
3270 DFF) 8-20 
maximum number of terminals in an MRT 
program 3-3 
MDT (see modified data tag) 
message and response prefixes (command 
mode) A-3 
message formats (attached command 
mode CPU) A-3 
message formatting for 3270 without DFF 
COBOL 4-17 
FORTRAN — 5-15 
RPG Il 6-31 
message lengths (attached command mode CCP) A-3 
message rnode operations 2-13 
definition B-2 
length of record area 2-15 
message sequences 
BTAM to CCP examples A-6 
method of access (disk files) 9-17 
MFCU file considerations 9-7 
MLMP 10CS — 2-12 
MLMP IOCS, definition B-2 


MLTA 10CS 2-12 : 
MLTA IOCS, definition B-3 
MLTA switched lines 3-20 
MLTA terminals, communicating with 2-11 
MLTA typewriter terminals 
device control characters 2-10 
MLTALINE assignment statement (see 
CCP System Reference Manual) 
mnotes (CCP basic assembler macros) 7-14 
mode of input operations 2-13 
length of record area 2-13 
with Put-Then-Get 2-22 
mode, command (CPU to CPU 
considerations) A-3 
modified data tag (MDT) 
definition B-2 
field characteristic 8-5 
field classes affected by setting 8-5 
ON or OFF 8-6 
Put Override 8-44 
modifiers, operation code 
RPG Il 6-10 
modify data indicator 8-46 
MRT (see multiple requesting terminal 
program) 
MRTMAX keyword = 3-3 
multicomponent terminals 2-5 
multicomponent terminals, definition B-3 
multiple output lines 
RPG Il programming consideration 6-30 
multiple requesting termimal (MRT) 
program 3-3 
multiple requesting terminal (MRT) program 
Accept Input in 3-3 
count of outstanding Invite Inputs 3-3 
COBOL programming example 4-24 
definition B-3 
FORTRAN progamming example 5-21 
maximum number of terminals 3-3 
MRTMAX keyword 3-4 
program logic example 3-13 
releasing requesting terminal 3-31 
Release Terminal operation 3-13 
RPG Il programming example 6-37 
shutdown return code 3-13, 3-15 
work areas for terminals 3-15 
3270 DFF example 8-72 
multipoint attachment (CPU to CPU) A-1, A-7 
multivolume disk files / 
restriction against use under CCP —_— 6-31, 9-8 
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name of label exit (RPG !I SPECIAL) 6-8 

NAME parameter of FILE 9-10 

name, program 2-4 

naming of terminals 2-4 

negative numbers 
RPG II EXIT/RLABL (3270 DFF) 6-25 
3270 DFF 8-19 

negative return codes 
general description 2-2, E-1 
summary tables  E-4 
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NEP (see never-ending program) 
never-ending program (NEP) 
definition B-3 
general description of attribute 3-4 
SRT 3-4 
New Line 
new fine (NL) orders, 3270 8-24, 8-37 
New Line, general description 2-11 
New Line, Put operation 2-20 
New Line, Put-Then-Get operation 2-22 
new screens 8-56 
non-display field characteristics (3270 DFF) 
output field types 8-7 
Selector Pen detectable field types 8-10 
non-!/O operations 
RPG I! EXIT/RLABL 6-23 
RPG II SPECIAL 6-12, 6-19 
nonswitched CPU to CPU A-1 
normal (successful) return code 2-2 
normal intensity output fields (3270 
DFF) 8-7 
Not New Line 2-11 
null character 8-11 
null character, definition B-3 
number of entries per array (RPG H}) 6-9 
number of entries per record (RPG II) 6-9 
number of fields in a display format 8-19 
numeric data (3270 DFF) 8-19 
numeric field 
defining (3270 DFF) 8-19 
field characteristic (3270 DFF) 8-5 
RPG Il EXIT/RLABL 6-25 


OCL considerations 
display format generator (3270 
DFF) 8-32 
symbolic files 3-16 
offsets for parameter list 
generating in basic assembler 7-2 
online processing 3-8 
online requirements (disk files) 9-8, 9-10 
online terminal testing (see 
CCP Operators Manual) 
online, information returned from Get 
Terminal Attributes 2-32 
OP-($NCIO macro operand) 7-10 
opening disk files 
considerations 9-8, 9-10 
symbolic files 3-17 
operation code 
(see also operations) 
COBOL parameter list 4-3 
FORTRAN parameter list 5-3 
generating in basic assembler (SNOPV 
macro) 7-3 
RPG Il 6-10 / 
parameter list 6-3 
setting in COBOL 4-5 
setting in FORTRAN 5-4 
RPG Il 6-13, 6-26 
summary table D-1 
operational stage of CCP 1-2, B-3 


operations 2-17 
Accept Input 2-27 
3270 DFF 8-53 
Acquire Terminal 2-34 
use of third parameter list field 2-3 
BSCA input 2-13 
Chain Task Request 2-35 
Copy (3270 DFF) 8-50 
Erase (3270 DFF) 8-53 
Forced End of File (RPG II) 6-11 
Get 2-18 
Get Terminal Attributes 2-30 
Get, 3270 DFF 8-53 
Invite Input 2-26 
3270 DFF 8-54 
message mode input 2-13 
non-|/O, performing in RPG li 6-12, 6-19, 6-23 
performing using RPG II SPECIAL 6-12 
performing, general steps 2-1 
PRUF Put Message 8-44 
PRUF Put Override 8-45 
Put 2-20 
Put Block 2-15 
Put Message 2-15 
3270 DFF 8-43 
Put Override 8-44 
Put Record 2-15 
Put with Invite input (RPG II) 6-11 
Put-No-Wait 2-24 
Put-No-Wait with Invite Input 
(RPG II) 6-11 
3270 DFF 8-44 
Put-Then-Get 2-22 
BSCA output 2-16 
RPG II SPECIAL 6-18 
Release Terminal 2-38 
3270 DFF 8-54 
setting parameters in basic 
assembler 7-8 
setting parameters in COBOL 4-4 
setting parameters in FORTRAN 5-3 
setting parameters in RPG II 6-11, 6-25 
Shutdown Inquiry 2-39 
standard interface 2-1 
Stop Invite Input 2-29 
3270 DFF 8-53 
valid operations with console 2-5 
wait 2-40 
3270 DFF operations 8-43 
operator identification card reader 
(3270 DFF) 8-60 
OPTIONS statement 9-3, 9-6 
order entry application definition B-3 
RPG II example (3270 DFF) 8-72 
organization and method of access of 
disk files 9-18 
OUTLEN-operand 
basic assembler $NCIO macro 7-11 
basic assembier $NPL macro 7-6 
output area data 8-46 
COBOL 4-9 
FORTRAN _ 5-6 
RPG Il 6-2 
Output data transfer 2-8 
output data translation 2-8 


output field class (3270 DFF) 8-4 
length in display layout 8-13 
output field types (3270 DFF) 8-7 
output file, definging in RPG Il 6-7 
output hald area (3270 DFF) 98-59 

output length 
output length 
COBOL 4-6 
data included 2-3 
FORTRAN 5-6 
multiple (RPG II) 6-30 
RPG Il 6-3, 6-18, 6-26 
output operations 
(see also operations) 


BSCA 2-15 
use of third parameter list 
field 2-3 


output record area (RPG II SPECIAL) 6-3, 6-20 
output record format (3270 DFF) 8-20 
output time, performing RPG II 
operations 6-11 
output/input field class (3270 DFF) 8-4 
entries on field definition form 8-26 
length in display layout 8-13 
output/input field types (3270 
DFF) 8-9 
output 
data source (3270 DFF) 
entry on field definition form 8-26 
type (3270 DFF) 
entry on field definition form 8-26 
outstanding Invite Inputs 
counting 2-3 
COBOL 4-13 
FORTRAN ~ 5-5 
RPG Il 6-30 
overlay linkage editor control 
statements 9-3 
overlay screens (3270 DFF) 8-56 
overlaying records (caution) 9-10, 9-12 


parameter array (RPG II) 
(see also parameter list) 
defining 6-9 
EXIT/RLABL 6-22 
SPECIAL -2 
summary -20 
when loaded 6-9 
parameter list 
address of the record area 2-4 
basic assembler 7-6 
CCP work area 2-4 
COBOL 4-1, 4-3 
effective input length 2-3 
FORTRAN | 5-1 
maximum input length 2-4 
RPG Il 6-2, 6-22 
setting fields 
basic assembler 7-7 
COBOL 44 
example 4-7 
FORTRAN ~ 5-3 
example 5-6 


parameter list (continued) 
setting fields (continued) 
RPG Il 6-11, 6-23 
example 6-13 
use of third field 2-3 
passward security option, definition B-3 
PAUSE statement (FORTRAN restriction) 5-13 
performing a communications operation 
general steps © 2-1 
performing CCP operations with SPECIAL 
(RPG II) 6-11 
PHASE statement 9-1, 9-3 
physical file 3-16 
planning the display layout (3270 DFF) 98-11 
platen length 8-34 
PLIST operand (§NCIO macro) 7-9 
point-to-point 
BTAM to CCP example A-8, A-9, A-11 
CPU to CPU considerations A-1 
positive (exception) return code 2-2 
pre-execution time array (RPG II) 6-9, 6-12 
preparing application programs to run 
under CCP 9-1 
primary input file (RPG Il SPECIAL) 
defining 6-7 
performing CCP operations with SPECIAL 
(RPG Il) 6-12, 6-13 
printable and unprintable format 
control characters (3270 DFF) 6-32 
printer 
control (3270 DFF) 8-24, 8-38 
name 8-34 
sharing (1403) 2-1 
size 8-34 
printer (3284/3286) device busy 2-16 
printer considerations, 3284/3286 2-16 
printer format generator routine 8-33 
control form 8-33 
diagnostic messages (see CCP 
Messages Manual) 
duplication 8-38 
field definition form 8-36 
layout sheet 8-33 
OCL 8-40 
printer control 8-33 
Printer/Keyboard (see CONSOL) 


printer 
control (3270 DFF) 8-24, 8-38 
name 8-34 
sharing (1403) 2-1 
size 8-34 


PROCESS statement 9-1, 9-3 
processing an input record area 
(3270 DFF) 8-20 
program access (PA) keys (3270 DFF) 8-60 
PROGRAM assignment statement 
determining the disk file access 
value 9-17 
PROGRAM assignment statement, 3270 
DFF considerations 8-58 
program attention keys (3270 DFF) 8-60 
program attributes 3-4 
program dump (see CCP System 
Reference Manual) 
program errors (see CCP Messages Manual) 
program function (PF) keys 8-60 
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program interface to CCP 2-1 
program logic examples 3-8 
program management 
definition B-3 
program name 2-4 
program preparation 9-1 
program request count B-3 
program request queueing (MRT program) 3-4 
program request under format (PRUF) 3-5 
PRUF RPG II order entry program 8-103 
data with 
maximum fength 2-7, 2-28 
single requesting terminal 3-9 
data with, symbolic files 3-17 
program request, definition B-3 
program request, procedure for issuing 
froma CPU A-5 
program selected terminals 3-2 
BSCA switched.-lines 3-2 
definition 3-2, B-3 
how selected 3-2 
restriction with certain terminals 3-2 
with multiple requesting terminals 3-15 
with single requesting terminal 3-11 
program termination codes 
program termination, controlled 2-40 
program testing 10-1 
program types 3-3 
program use of terminals 3-2 
programming a user security routine 
Model 10 and 12 =7-16 
Model 15 7-22 
programming considerations 
COBOL 4-15 
FORTRAN | 5-13 
RPG Il 6-29 
programming examples 
user security routine 7-19, 7-23 
COBOL 
MRT 4-24 
SRT 4-17 
3270 DFF 8-100 
FORTRAN 
3270 DFF 8-102 
FORTRAN/MRT 5-21 
FORTRAN/SRT 5-15 


RPG II 
MRT 6-37 
SRT 6-31 


3270 DFF 8-72, 8-99 

programming restrictions 

basic assembler 7-14 

COBOL 4-15 

FORTRAN _ 5-13 

RPG II 6-31 
programming user security routine 

Model 10 and 12 7-16 

Model 15 = =7-22 
prologue, transient 

programming a user security routine 7-16 
protected field 8-5 

definition B-3 
PRUF (program request under format) 3-5 © 
PRUF program request length 3-7 
PRUF Put Message 8-44 
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PRUF Put Override 8-45 
PRUFLNG 3-6 
Put 2-20 
blank terminal name 3-9 
RPG Il 6-12 
with Invite Input 6-11 
Put Block 220 
BSCA output operation 2-15 
RPG Il 6-12 
Put Message 2-20 
BSCA output operation 2-15 


PRUF 8-44 
RPG Il 6-12 
3270 8-43 


Put Override (PRUF) 8-45 
3270 DFF 8-45 
selecting the WCC 8-49 
Put Record 2-15 
Put with Invite Input 6-11 
Put-No-Wait 2-24 
BSCA output operation 2-16 
RPG Il 6-11, 6-12 
with Invite Input 6-11 
3270 DFF 8-44 
Put-Then-Get 2-22 
BSCA output operation 2-16 
COBOL 4-15 
output data area 4-9 
FORTRAN _ 5-13 
mode of input operation 2-22 
RPG II SPECIAL 6-18 
Put, blank terminal name 3-9 
Put, RPG Il 6-12 
Put, with Invite Input 6-11 


READ (FORTRAN restriction) 5-13 
READ operation (RPG II) (see demand files) 
RECA-operand (basic assembler) 
$NCIO macro 7-11 
$NPL macro 7-6 
record area 
address 2-4 
COBOL 4-1 
setting contents 4-4 
contents by operation code and return code _ _E-13 
exceptions to standard format 2-4 
FORTRAN _ 5-1 
setting 5-3, 5-6 
Get Attributes operation 2-31 
illustration of standard format 2-4 
input and output formats (3270 DFF) 8-20 
processing (3270 DFF) 8-20 
RPG Il EXIT/RLABL format 6-23 
RPG Il SPECIAL format 6-2 
standard interface elements 2-1 
user program, calculating size (3270 
DFF) 8-54 
record concept 8-20 
record length 2-15 
record length zero 
record length zero, Put Block operation 2-15 
record length, RPG If SPECIAL 6-8 


record mode operations 2-13 
BSCA 2-8 
definition B-3 
length of record area 2-15 
record separators 2-9 
device control character 2-9 
input data transfer 2-7 
redefining the record area (COBOL) 4-2 
referencing saved information 3-11 


COBOL 4-13 
FORTRAN 5-11 
RPG Il 6-15 


Release Terminal operation 2-38 
checking count of outstanding Invite Inputs 
keep line 2-38 
multicomponent terminals 2-6 
multiple requesting terminals 3-3, 3-13 
opening files (COBOL and basic assembler) 2-39 
RPG II programming consideration 6-30 
RPG Ii, when to issue 6-19 
switched line 3-17, 3-20 
symbolic file consideration 2-39 
use of third parameter list field 2-3 
3270 DFF 8-54 

relocation address table 7-17 

repeat last character 8-37 

requesting terminal ; 

BSCA 3-18 
definition B-3 
general description 3-2 
requests for programs (see program requests) 
reserved indicators 9T and 92 
(RPG It) 6-5 

restrictions, programming 

programming 
basic assembler 7-14 
COBOL 4-15 
FORTRAN 5-13 
RPG II 6-31 

return code 
-91 +6-11 
basic assembler 7-3 
COBOL 43 
data truncated (3270 DFF) _E-1 
FORTRAN _ 5-2, 5-9 
negative £-1 

3270 DFF 8-53 

per operation type  E-8 
RPG II EXIT/RLABL 6-29 
RPG | SPECIAL 6-3, 6-14 
shutdown requested 2-28 
standard parameter list 2-2 
summary tables E-1 
08 return code (RPG II 

consideration) 6-29 
3270 DFF 8-53 

returned information, examining 
COBOL 4-11 
FORTRAN 5-9 

reverse interrupt (RVI) 2-18 

RLABL 
for RPG Il 

SUBR90- 6-24 
SUBR91 6-22 
RPG II Chain Task Request 6-25 


RPG II inquiry feature restriction 6-31 
RPG I, 

compiling program 9-1 
core index 6-1 
count of outstanding Invite Inputs 6-3 
defining SPECIAL files 6-5 
determining the disk access value 9-19 
examining returned information 6-14, 6-29 
EXIT/RLABL interface 6-21 

when used 6-1 
Force End of File operation 6-11 
handling printable and unprintable 

3270 format control characters 6-32 

indicators reserved for CCP use 6-5 
non-I/O operations 6-12, 6-19, 6-23 
operation codes 6-10 
parameter array for SPECIAL 6-2 

defining 6-9 — 
performing CCP operations with 

SPECIAL 6-11 

program preparation 9-1 
programming considerations 6-29 
programming examples 

MRT program 6-34 

SRT program 6-31 

3270 DFF inquiry program 8-95 

3270 DFF order entry program 8-72 
Put with Invite Input 6-11 
Put-No-Wait with Invite Input 6-11 
Put-Then-Get 6-18 
record area 

EXIT/RLABL 6-22 

SPECIAL 6-2 
SPECIAL interface 6-2 

when used 6-1 
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SUBR91 6-21 
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unidentified record halt, avoiding 6-19, 6-39 
use of the standard interface 6-1 

RVI 2-18 

RVI, definition B-4 


saved information, referencing 3-11 
COBOL 4-13 
FORTRAN _ 5-11 
RPG il 6-15 
screen, entry on display control form 
(3270 DFF) 8-22 
secondary file (RPG Il SPECIAL) 
defining 6-7 
performing CCP operations 6-12 
security routine, programming 
security routine, programming 
Model 15 7-22 
Models 10 and 12 97-16 
selecting input fields (3270 DFF) 8-45 
selecting the Copy Control Character 
(3270 DFF) 8-52 
selecting the WCC (3270 DFF) 8-49 
selection fields (SPD field type) 8-10 
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Selector Pen Detectable (SPD) field 
definition B-4 
field class 8-4 
field types 8-10 
modified data tag 8-6 
planning the display layout 8-14 
serially reusable program 3-5 
symbolic files 3-17 
set assignment 1-2 
set attributes (Acquire Terminal 
operation) 2-34 
set control information for communications 
operation 7-8 
setting fields in the parameter list 
COBOL 4-4 
FORTRAN _ 5-3 
RPG I! EXIT/RLABL 6-23, 6-25 
RPG SPECIAL 6-3, 6-12 
setting the record area 
COBOL 4-7 
FORTRAN 5-6 
‘RPG IT EXIT/RLABL 6-22 
RPG II SPECIAL 6-2, 6-15 
sharing access to disk files 
between program levels/partitions 9-8, 9-11 
Model 10 considerations 9-13 
Model 15 considerations 9-13 
sharing unit record devices 9-7 
sharing 1403 printer 2-2 
shutdown = 1-2 
Shutdown Inquiry operation 2-39 
never-ending program 3-5 
when to issue in RPG II SPECIAL 6-19 
shutdown record code, multiple requesting 
terminals 3-13, 3-15 
shutdown requested by operator 2-29 
shutdown return code 2-29 
Accept Input consideration 2-29 
never-ending program 3-5 
single requesting terminal 3-11 
sign-on security routine 7-16 
sign-on, definitin B-4 
single requesting terminal (SRT) program 
COBOL 4-17 
definition B-4 
FORTRAN example 5-15 
general description 3-3 
logic 3-9, 3-11 
multiple copies running 3-3 
RPG Il 6-31 
3270 DFF examples 
COBOL 8-100 
FORTRAN IV 8-102 
RPG Il 8-95 
sort programs 3-7 
sorts and task chaining 3-8 
sorts with chain task requests 2-36 
space requirements for field classes 
(3270 DFF) 8-11 
spanned records 2-9 
spanned records, Get Terminal Attributes 2-33 
SPD field (see Selector Pen Detectable field) 
SPECIAL files (RPG II) 
CCP communication interface 6-1, 6-2 
communications service subroutines 6-3 


SPECIAL files (RPG II) (continued) 
defining 6-5 
defining the parameter array 6-9 
false SPECIAL file 6-11 
Force End of File operation 6-11 
indicators reserved for CCP use 6-5 
parameter array 6-2 
performing CCP operations 6-11, 6-20 
Put-Then-Get operation 6-18 
record area 6-2, 6-20 
summary 6-20 
using both SPECIAL and EXIT/RLABL 6-30 
special program attributes 3-4 
spooling unit record devices (Model 
15) 9-8, 9-10 
SRT program (see single requesting terminal 
program) 
stages of CCP. 1-1 
standard application program interface 
to the CCP 
COBOL use 4-1 
FORTRAN IV use_ 5-1 
RPG ll use 4-1 
standby mode, definition B-4 
start address of CCP user programs 
(Model 15) 9-1 
starting location of field (3270 DFF) 98-11 
startup 1-2 
Stop Invite Input operation 2-29 
Stop Invite Input operation, 3270 DFF 8-53 
STOP statement (COBOL restriction) 4-15 
storage areas (3270 DFF) 8-58 
store and forward A-1 
subhost 1-1 
subhost, definition B-4 
subroutines for communications services 2-2 
SUBR87_— 6-25 
SUBR88 6-25 
SUBR90_ 6-21 
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SUBR92 6-3 

end of file 6-31 
SUBR93 «6-3. 


subterminal names 2-6 
success/exception return codes per 
operation type  E-8 
supervisor functions of CCP 
(see CCP System Reference Manual) 
supported terminals and features 1-3 
switch lines 


allocation 
BSCA 3-17 
MLTA 3-20 


answering 3-17 
auto answer 3-17 
auto call 3-17 


BSCA 3-17 
BTAM to CCP example A-9 
calling 3-17 


command terminals 3-17 

CPU to CPU considerations A-1 
data set number 3-17 

data terminals 3-17 

definition 3-17 

disconnect considerations 3-20 
exchange ID characters 3-17 


switch lines (continued) 
Invite Input operation 3-17 
manual answer 3-17 
manual call 3-17 
MLTA 3-20 
Release Terminal operation 3-17 
telephone number 3-17 
symbolic files 
definition B-4 
description 3-16 
symbolic subterminal name 2-6 
definition B-4 
symbolic terminal name 
blank name = 2-5 
classes 2-4 


CONSOL 2-5 
examining after an operation 
COBOL 4-13 


FORTRAN 5-9 
RPG Il EXIT/RLABL 6-15 
RPG II SPECIAL 6-13, 6-13 
multicomponent terminals 2-6 
Operations not requiring 2-5 
rules for forming 2-4 
symbolic terminal name, specifying 
COBOL 4-7, 4-9 
FORTRAN 5-6 
RPG I| EXIT/RLABL 6-22 
RPG || SPECIAL 6-3, 6-13 
user-defined 2-4 
SYMEFILE. statement 
symbolic files 3-16 
CONSOL considerations 2-5 
Release Terminal considerations 2-39 
system equates (user security routine) 7-16 
system resources, management by CCP 
(see CCP System Reference Manual) 
SYSTEM statement 
3270 DFF considerations 8-58 
system task (definition) B-4 
System/3 features supported by CCP 1-3 
System/360, System/370 features supported 
by CCP 1-3 
System/7 features supported by CCP 1-3 


table file (RPG I! restriction) 6-31 
task chaining and sorts 3-8 
task indentification B-4 
task management (see CCP System Reference 
Manual). 
telephone number 3-17 
teleprocessing line control characters 2-7 
TERMATTR statement 
default 2-35 
3270 DFF considerations 98-58 
terminal allocation 2-1 
terminal attributes 
definition B-4 
general description 2-6 
terminal attributes 
(see also Get Terminal Attributes) 
terminal class 3-1 
returned from Get Terminal Attributes 
operation 2-31 


terminal name (see symbolic terminal name) 
terminal operator actions (3270 DFF) 8-59 
terminal reference identifier, definition B-4 
termina! sign-on security routine 
(user-written) 7-16 ; 
terminal unit block (TUB) 2-31 
terminals and features supported 1-3 
terrninating attribute 9-13 
termination code 2-17 
termination of user programs 
program errors 2-17 
Shutdown Inquiry operation 2-40 
testing programs 10-1 
testing return codes (see return code) 
text transparency 
COBOL record area consideration 4-1 
third parameter list field 2-3 
TIME operation (RPG II) 2-16 
TNAME operand ($NCIO macro) 7-12 
To Terminal (3270 DFF Copy operation) 8-50 
total output (RPG Il SPECIAL) 6-7, 6-15, 6-18 
TP buffer 8-59 
transfer of input data 2-6 
transfer of output data 2-8 
transient prologue and equates 7-16 
translation error (BSCA) —_E-1 
translation of data. 2-7 
transmission code 2-7 
transparency 
COBOL record area consideration 4-1 
Get Terminal Attributes 2-33 
tributary station, definition B-4 
truncated data 2-7 
truncated return code in 3270 DFF_ E-1 
truncation, definition B-4 
TUB (terminal unit block) 2-31 
TYPER statement (FORTRAN restriction) 5-13 
types of fields (3270 DFF) 8-6 
types of fields (3270 DFF), entry of 
field definition form 8-26 
typewriter terminals, device control 
characters 2-10 
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(RPG II SPECIAL) 6-19 
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5203 printer considerations 9-7 
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